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Preface 


Intended Audience 

This manual is intended for all users of the OpenVMS operating system. 

A system manager performs the administrative tasks that create and maintain 
an efficient computing environment. If you are a system manager or want to 
understand system management concepts and procedures, refer to the OpenVMS 
System Manager's Manual. 

Document Structure 

This manual contains 18 chapters, 4 appendixes, and a glossary. Each chapter 
describes concepts and procedures for performing computing tasks. Basic 
information is presented first within each chapter; more complex concepts and 
procedures are presented last. 


Getting Started 


Location Content 


Chapter 1 


Chapter 2 


Chapter 3 


Chapter 4 


Chapter 5 


Introduction: OpenVMS Concepts and Definitions 

Describes basic concepts about the OpenVMS operating system and its 
components. The chapter serves as an introduction to the rest of the 
manual. 

Getting Started: I nteracting with the OpenVMS Operating System 

Describes how to log in and log out of the system, how to change your 
password, and how to get help. 

The DIGITAL Command Language: I nteracting with the System 

Describes how to use the DIGITAL Command Language (DCL). It includes 
a summary of keypad key combinations that let you enter and edit DCL 
commands. 

Files: Storing I nformation 

Describes files and how you can use them to store information. It includes 
examples for creating, copying, renaming, displaying, deleting, protecting, 
and printing files. 

Directories: Organizing and Managing Files 

Describes how to use directories to organize and manage files. 
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Communicating with Other Users 

Location 

Content 

Chapter 6 

Mail: Communicating with Other Users 

Describes how to use the Mail utility (MAI L) to communicate with other 
users on your system or on any other computer that is connected to your 
system with the DECnet for OpenVMS network. The chapter includes 
a sample mail message, step-by-step instructions for reading, sending, 
replying to, forwarding, and organizing mail messages, and a summary of 
Mail commands. 

Chapter 7 

Phone: Communicating with Other Users 

Describes how to use the Phone utility (PHONE) to communicate with 
other users on your system or on any any other computer that is connected 
to your system with the DECnet for OpenVMS network. 

Processing Text and Sorting Records 

Location 

Content 

Chapter 8 

Editing Text Files: Using EVE 

Describes EVE, an interactive text editor that is included with the 
OpenVMS operating system. The chapter describes how to use EVE to 
create and edit new files or to edit existing files. It includes a summary of 
EVE commands. 

Chapter 9 

Editing Text Files: Using EDT 

Describes EDT, an interactive text editor that preceded EVE and is still 
included with the OpenVMS operating system. The chapter describes how 
to begin and end an EDT session, how to enter EDT commands, and how 
to get help in EDT. It includes a summary of EDT commands. 

Chapter 10 

DIGITAL Standard Runoff (DSR): Formatting Text Files 

Describes the DIGITAL Standard Runoff (DSR) text-formatting facility. 
The chapter includes a summary of DSR commands. 

Chapter 11 

Sort/Merge Utility: Sorting and Merging Files 

Describes how to use the Sort/Merge utility (SORT/M ERGE) to sort records 
from one or more input files or to merge files that have been sorted. The 
chapter includes a summary of Sort/Merge command qualifiers. 

Using Devices 

Location 

Content 

Chapter 12 

Devices: Using Private Tapes and Disks 

Describes how to reserve tapes or disks for private use. Unlike devices 
that are shared by a group of users, private devices might not be set up 
and maintained by a system manager. 


XX 



Using Logical Names and Symbols 

Location 

Content 

Chapter 13 

Logical Names: Defining Names for Devicesand Files 

Describes how to create and use logical names to represent files, 
directories, and devices. The chapter also summarizes the logical names 
created by the system. 

Chapter 14 

Symbols: Defining Commands and Expressions 

Describes how to use symbols to represent commands, character strings, 
and numeric data. The chapter also describes how to combine symbols into 
expressions to manipulate the values that the symbols represent. 

Writing Programs and Using Programming Functions 

Location 

Content 

Chapter 15 

Command Procedures: Programming with DCL 

Describes how to write and use command procedures, which are files that 
contain DCL commands and data lines used by DCL commands. 

Chapter 16 

Lexical Functions: Obtaining and Manipulating 1 nformation 

Describes how to use lexical functions within a command procedure to get 
information about your process or the system environment. 

Managing Processes 

Location 

Content 

Chapter 17 

Processes and Batch J obs: Using the OpenVMS Environment 

Describes processes, which are environments created by the OpenVMS 
operating system that let you interact with the system. The chapter 
describes how and when to use subprocesses, programs, and batch jobs. 

Ensuring Security 

Location 

Content 

Chapter 18 

Security: Controlling Access to Resources 

Describes general security issues such as controlling access to protected 
objects and accessing data on remote systems. 
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Reference Section 

Location 

Content 

Appendix A 

Customizing EVE 

Contains information on customizing your EVE editing environment. 

Appendix B 

Character Sets 

Describes the DEC Multinational character set and the DCL character set. 

Appendix C 

Annotated Command Procedures 

Contains complete command procedures that demonstrate the concepts 
and techniques discussed in Chapters 15 and 16. 

Appendix D 

Terminal Keys 

Describes how the OpenVMS operating system responds when various 
keys and control characters are pressed on an LK201 keyboard (VT200 
series and later terminals, and workstations) or on a VT100 series 
terminal. 


Glossary 


Location Content 

Glossary Glossary 

Provides a list of terms used in this manual. 

This document includes information from the following documents that have been 
discontinued: 

• VMS Mail Utility Manual 

• VMS Sort/ Merge Utility Manual 

• / ntroduction to VMS 

• Guide to Using VMS Command Procedures 

• VMS DCL Concepts Manual 

• C ui de to VM S Text Processing 

• Guide to VMS Files and Devices 

• VMS Phone Utility M anual 

Associated Documents 

For more information, refer to the following manuals: 

• The Overview of OpenVMS Documentation provides an overview of the 
OpenVMS documentation set. 

• The OpenVMS DCL Dictionary provides complete descriptions of all Dl GITAL 
Command Language (DCL) commands and lexical functions. 

• The Extensible Versatile Editor Reference M anual provides a summary of EVE 
commands. 

• The DEC Text Processing Utility Reference M anual provides information on 
theDECTPU programming language. 

• The OpenVMS EDT Reference Manual describes the EDT editor and the EDT 
commands for each editing mode. 


XXII 


• The Open VMS DIGITAL Standard Runoff Reference Manual describes 
DIGITAL Standard Runoff (DSR). It includes descriptions of all the DSR 
commands, flags, and control characters. 

• The OpenVMS Guide to System Security provides detailed information on how 
to create a secure system. 

• The Open VMS System M anager's M anual provides information on managing 
your system. 

• The OpenVMS National Character Set Utility Manual provides information 
about the National character set (NCS) utility. 

• The OpenVMS System Management Utilities Reference M anual describes the 
utilities and commands that are used by system managers. 

• The OpenVMS Command Ddinition, Librarian, and M essage Utilities Manual 
provides information on how to define foreign commands using the Command 
Definition utility. 


Conventions 


In this manual, every use of OpenVMS AXP means the OpenVMS AXP operating 
system, every use of OpenVMS VAX means the OpenVMS VAX operating system, 
and every use of OpenVMS means both the OpenVMS AXP operating system and 
the OpenVMS VAX operating system. 

The following conventions are used to identify information specific to OpenVMS 
AXP or to OpenVMS VAX: 



The AXP icon denotes the beginning of information 
specific to OpenVMS AXP. 



The VAX icon denotes the beginning of information 
specific to OpenVMS VAX. 


♦ 


The diamond symbol denotes the end of a section of 
information specific to OpenVMS AXP or to OpenVMS 
VAX. 


The following conventions are also used in this manual: 


Ctrl/x 


A sequence such as Ctrl/x indicates that you must hold down 
the key labeled Ctrl while you press another key or a pointing 
device button. 


PF1 x 


A sequence such as PF1 x indicates that you must first press 
and release the key labeled PF1 and then press and release 
another key or a pointing device button. 


GOLD x 


A sequence such as GOLD x indicates that you must first 
press and release the key defined as GOLD and then press 
and release another key. GOLD key sequences can also have 
a slash (/), dash (-), or underscore (_) as a delimiter in EVE 
commands. 


The GOLD key definition is often mapped to the PF1 key on 
the keypad. 
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| Return | In examples, a key name enclosed in a box indicates that 

you press a key on the keyboard. (In text, a key name is not 
enclosed in a box.) 

Horizontal ellipsis points in examples indicate one of the 
following possibilities: 

• Additional optional arguments in a statement have been 
omitted. 

• The preceding item or items can be repeated one or more 
times. 

• Additional parameters, values, or other information can be 
entered. 

Vertical ellipsis points indicate the omission of items from 
a code example or command format; the items are omitted 
because they are not important to the topic being discussed. 

( ) In command format descriptions, parentheses indicate that, if 

you choose more than one option, you must enclose the choices 
in parentheses. 

[ ] In command format descriptions, brackets indicate optional 

elements. You can choose one, none, or all of the options. 
(Brackets are not optional, however, in the syntax of a directory 
name in an OpenVMS file specification or in the syntax of a 
substring specification in an assignment statement.) 

{} In command format descriptions, braces surround a required 

choice of options; you must choose one of the options listed. 

boldface text Boldface text represents the introduction of a new term or the 

name of an argument, an attribute, or a reason (user action 
that triggers a callback). 

Boldface text is also used to show user input in Bookreader 
versions of the manual. 

italic text Italic text emphasizes important information and indicates 

complete titles of manuals and variables. Variables include 
information that varies in system messages (Internal error 
number), in command lines (/PRODUCER=name), and in 
command parameters in text (where da/i ce-name contains up 
to five alphanumeric characters). 

UPPERCASE TEXT U ppercase text indicates a command, the name of a routine, 

the name of a file, or the abbreviation for a system privilege. 

A hyphen in code examples indicates that additional 
arguments to the request are provided on the line that follows. 

numbers All numbers in text are assumed to be decimal unless 

otherwise noted. Nondecimal radixes— binary, octal, or 
hexadecimal— are explicitly indicated. 

In this manual, discussions that refer to VMScluster environments apply to both 
VAXcluster systems that include only VAX nodes and VMScluster systems that 
include at least one AXP node, unless indicated otherwise. 

The display examples for some commands described in this manual may differ 
from the actual output from these commands on your system. However, when 
the behavior of a command differs significantly between OpenVMS VAX and 
OpenVMS AXP, that behavior is described in text and rendered, as appropriate, 
in separate examples. 
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Introduction: Open VMS Concepts and 

Definitions 


OpenVMS is an interactive virtual memory operating system. While you are 
logged in to the computer, you and the system conduct a dialogue using the 
DIGITAL Command Language (DCL). You use DCL by entering commands, 
which the system reads and translates. You enter a command by typing it from 
your keyboard and pressing the Return key; the system responds by executing 
the command or by displaying an error message on the screen if it cannot 
interpret what you entered. 

For complete information on DCL commands, lexical functions, qualifiers, and 
syntax, see the Open VMS DCL Dictionary. Note that although standard DCL 
commands are documented in the OpenVMS DCL Dictionary, system managers 
can tailor their systems to support the local environment. A system manager 
might decide: 

• To use a different command language interpreter 

• To change the default action of some standard DCL commands so that they 
do not reflect what is described in the OpenVMS documentation 

• To disable some DCL commands 

• To alter some system defaults, such as the DCL prompt 

This chapter describes basic concepts about the OpenVMS operating system and 
its components. 

1.1 Logging In to the System 

To interact with the operating system, you must log in to a user account. An 
account is a name or number that identifies you to the system when you log in. 
That name or number tells the system where your files are stored and the type of 
access you have to other files. 

Your system manager (or whoever authorizes system use at your installation) 
usually sets up accounts. This person grants privileges according to your needs 
and provides you with your user name and initial password. The type of access 
rights and privileges enabled for your account determine whether you have access 
to files, images, or utilities that might affect system performance or other users. 
Your user name identifies you to the system and distinguishes you from other 
users. In many cases, a user name is your first or last name. Your password is 
for your protection. If you maintain its secrecy, other users cannot use system 
resources under your user name. 

Logging in consists of gaining access to the system and identifying yourself as 
an authorized user. When you log in, the system creates an environment from 
which you can enter commands. This environment is called your process (see 
Section 1.15). 
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1.1 Logging In to the System 

Chapter 2 describes how to log in to and out of the system. 

1.2 Using a Network 

Your system might be part of a DECnet for OpenVMS network. When computer 
systems are linked together, they form a network. Operating systems in a 
DECnet network are able to communicate with each other and share information 
and resources. Each system in a network is called a network node and is 
identified by a unique node name. 

When you are logged in to a network node, you can communicate with other 
nodes in the network. The node at which you are logged in is called the local 
node; other nodes on the network are called remote nodes. If you have access 
to an account on a remote node, you can log in to that account from your local 
node and perform tasks on that node while remaining connected to your local 
node. 

Because of support provided by DECnet, programs can execute across the 
network as if they were executing locally. Because DECnet is integrated within 
the operating system, it is easy to write programs that access remote files. 

To access a remote file in an application program, you need only include the 
name of the remote node and any required access control information in the file 
specification. 

Task-to-task communications, a feature common to all DECnet implementations, 
allows two application programs running on the same or different operating 
systems to communicate with each other regardless of the programming 
languages used. Examples of network applications are distributed processing 
applications, transaction processing applications, and applications providing 
connection to servers. 

Chapter 2 describes how to log in to a remote node. Additional tasks you can 
perform on remote nodes are described in the appropriate chapters of this 
manual. 


Note 

I n the examples of remote operations in this manual, proxy accounts 
enable users to perform operations on remote systems. Proxy accounts 
are one way users can access remote systems. For additional ways to 
access remote systems, see the OpenVMS System Manager's Manual. 


1.3 DIGITAL Command Language (DCL) 

DCL (Dl GITAL Command Language) is a set of English-like instructions that tell 
the operating system to perform specific operations. DCL provides you with over 
200 commands and functions to use in communicating with the operating system 
to accomplish computing tasks. 
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1.3.1 Using Interactive and Batch Modes 


You can use DCL in the following two modes: 

• Interactive 

In interactive mode, you enter commands from your terminal. One 
command has to finish executing before you can enter another. 

• Batch 

I n batch mode, the system creates another process to execute commands 
on your behalf. A batch job is a command procedure or program that is 
submitted to the operating system for execution as a separate user process. 
After you submit the command procedure for batch execution, you can 
continue to use your terminal interactively. 

Batch jobs and network processes use DCL in batch mode. See Section 1.15 
and Chapter 17 for more information about processes. 


1.3.2 Using Different Types of DCL Commands 


When you enter a DCL command, it is read and translated by the DCL 
interpreter. The way the command interpreter responds to a command is 
determined by the type of command entered. The three types of DCL commands 
are as follows: 

• Built-in commands 

These commands are built into the DCL interpreter and are executed 
internally. Table 1-1 lists the DCL built-in commands. 

Table 1-1 DCL Built-In Commands 


ATTACH 

CLOSE 

CREATE/NAM E_TABLE 

DEBUG 

DEFINE/KEY 

DEPOSIT 

EOD 

GOSUB 

INQUIRE 

READ 

SET CONTROL 
SET ON 

SET PROTECTION/DEFAULT 

SHOW DEFAULT 

SHOW QUOTA 

SHOW TIME 

STOP 


ALLOCATE 

CALL 

CONNECT 

DEALLOCATE 

DECK 

DELETE/KEY 

DISCONNECT 

EXAMINE 

GOTO 

ON 

RECALL 
SET DEFAULT 
SET OUTPUT_RATE 
SET UIC 
SHOW KEY 
SHOW STATUS 


ASSIGN 

CANCEL 

CONTINUE 

DEASSIGN 

DEFINE 

DELETE/SYMBOL 

ENDSUBROUTINE 

EXIT 

IF 

OPEN 

RETURN 

SET KEY 

SET PROMPT 

SET VERIFY 

SHOW PROTECTION 

SHOW SYMBOL 


SHOW TRANSLATION SPAWN 


SUBROUTINE 


WAIT 


(continued on next page) 
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Table 1-1 (Cont.) DCL Built-In Commands 

WRITE 


• Commands that invoke programs 

DCL calls another program to execute the command rather than executing 
it internally. The program invoked to execute a command is referred to 
as a command image. This command image can be either an interactive 
program, a utility (such as Mail), or a noninteractive program (such as 
COPY). 

• Foreign commands 

A symbol that executes an image is referred to as a foreign command. 

(See Section 1.12 for more information about symbols.) A foreign command 
executes an image whose name is not recognized by the command interpreter 
as a DCL command. The following example defines the symbol FUN as a 
foreign command. (No DCL command FUN exists.) 

$ FUN := $DISK1: [R0Y.PR0GRAMS1GAMES.EXE |Rit5EU 

1.3.3 The DCL Command Line 

DCL, like any language, has its own vocabulary and usage rules. The vocabulary 
consists of commands, parameters, and qualifiers, which are put together in a 
way that DCL can interpret. The way in which the parts of a command line are 
put together is referred to as the command line syntax. A DCL command line 
contains the following format: 

[$] command [[/qualifier[=value]]...] [[parameter[=value][/qualifier.. .]]...] 

Note 

Items in brackets [ ] are optional and might not be required by a specific 
command. 


For a description of the components of a DCL command line, see Section 3.2.1. 
Chapter 3 shows a sample command line and describes how to use DCL 
commands. 

The OpenVMS DCL Dictionary describes all DCL commands and lexical 
functions. Lexical functions are command language constructs that the DCL 
interpreter evaluates and substitutes before it interprets a command string. 
Chapter 16 discusses lexical functions in more detail. 

1.4 Files and Directories 

A file contains information. This information can be machine-readable data that 
the computer understands. It can also be text you enter and manipulate. The 
text in the file might be the text of a document, a program, or a list of addresses. 
You can examine the data in these files by displaying the files on a terminal 
screen or by printing them on paper. 

A file is listed in a directory. A directory is a special kind of file that contains 
the names and locations of files. For example, when the system manager creates 
a user account for you (see Section 1.1), you automatically have a directory with 
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the same name as your user name. If your user name is J ONES, the directory is 
U ONES], 

Directory files are stored on disks. Disks are one type of hardware device 
that the operating system uses to store information. See Section 1.10 for more 
information about disks. 

Chapter 4 describes how to create and organize files to store information. 
Chapter 5 describes how to use directories to organize and manage files. 

1.4.1 File and Directory Specifications 

Every file must have a file name or file type to identify it to both the system 
and you. A file also has a version number. You can have several versions of a 
file. Unless you specify a version number, the system uses the highest existing 
version number of a file. When you edit a file, the system saves the original file 
and produces a modified output file. By default, the output file has the same 
name and type as the original but the version number is incremented by one. 

The file name, file type, and version number form a file specification. A full 
file specification completely describes the access path the system uses to locate 
and identify a file. I n addition to the file name, a file specification can include 
the directory in which the file is located and the network node on which the file 
resides. A full file specification is also known as a network file specification. 

1.4.2 Directory Structures 

Each disk contains a main directory, which can be set up by a system manager or 
by the system itself. This main directory is called the master file directory (MFD) 
and contains a list of user file directories (UFDs). UFDs are files in the master 
file directory that point to top-level directories. Your top-level directory is usually 
your login or default directory. Unless your account has been modified to do 
otherwise, the system automatically places you in your top-level directory when 
you log in. 

In most cases, a UFD exists for each user on the system. It contains the names of 
and pointers to files cataloged in a user's directory. A subdirectory is a directory 
file within another directory or subdirectory file. You can have up to seven levels 
of subdirectories. Subdirectories let you organize files into meaningful groups. 

For example, you might have one subdirectory that contains memos and another 
subdirectory for status reports. 

Like a directory, a subdirectory contains names and pointers for the files 
cataloged within it. It can contain an entry for another subdirectory, which 
can contain an entry for another subdirectory, and so on to seven levels of 
subdirectories. This structure (a top-level directory plus a maximum of seven 
levels of subdirectories) is called a hierarchical directory structure. Chapter 5 
contains more information about directory structures. 

1.5 The OpenVMS Mail Utility 

The OpenVMS Mail utility (MAIL) lets you send messages to and receive 
messages from other users on your system or on any computer that is connected 
to your system by DECnet. 

Chapter 6 describes how to use Mail. 
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1.6 The OpenVMS Phone Utility 

The OpenVMS Phone utility (PHONE) lets you communicate with other users on 
your system or on any computer that is connected to your system by DECnet. 

Chapter 7 describes how to use Phone. 

1.7 Text Editors 

Text editors allow you to create and modify text files. With a text editor, you 
can enter text from a keyboard and modify the text using text editing commands. 
For example, you can type in data for a report and then rearrange sections, 
duplicate information, substitute phrases, or format text. You can use text editors 
to create and modify source files for programming languages (such as DEC C 
for OpenVMS or VAX BASIC) or text formatters (such as VAX DOCUMENT or 
DIGITAL Standard Runoff). The operating system supports several text editors. 
Chapter 8 describes how to use EVE, and Chapter 9 describe how to use EDT. 

1.8 DIGITAL Standard Runoff (DSR) 

DIGITAL Standard Runoff (DSR) is a text formatter that processes source files 
into formatted text and intermediate files, and creates tables of contents and 
indexes. You use a text editor to create a source file, to which you should give a 
file type of .RNO. This file contains text, DSR formatting commands, flags (special 
instruction characters you insert), and control characters. 

Chapter 10 describes how to use DSR and lists DSR commands. 

1.9 The OpenVMS Sort/Merge Utility 

The OpenVMS Sort/Merge (SORT/MERGE) utility can be invoked in two ways: 
by using the SORT command, or by using the MERGE command. When you 
invoke the Sort/Merge utility with the DCL command SORT, it sorts records 
from one or more input files according to the fields you select and generates one 
reordered output file. You can use the Sort/Merge utility to reorder records in a 
file (or files) so that they are in alphabetic or numeric order, and either ascending 
or descendi ng order. 

When you invoke the Sort/Merge utility with the DCL command MERGE, it 
combines up to ten previously sorted files into one ordered output file. 

For information about using the Sort/Merge utility, see Chapter 11. 

1.10 Devices 

In the OpenVMS operating system, devices are classified as follows: 

• Mass storage devices 

These devices, such as disks and magnetic tapes, save the contents of 
files on a magnetic medium. Files saved this way can be accessed, updated, 
modified, or reused at any time. 

• Record-oriented devices 

These devices, such as terminals, printers, mailboxes, and card readers 
read and write only single physical units of data at a time and do not 
provide online storage of the data. (Printers and card readers are also called 
unit-record devices.) 
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The files you commonly access are stored on disks or magnetic tapes. Your 
user file directory (UFD) and your default directory with all your files and 
subdirectories are located on a disk. You can use a file specification that contains 
directory information only if the file is located on a disk. Magnetic tapes do not 
have directory structures. To obtain a file stored on tape, use a file specification 
that contains only file information. 

Chapter 5 describes how to access files that are not on your default device. 
Chapter 12 describes how to use private volumes, which are tape and disk 
devices that are not available systemwide. 

1.11 Logical Names 

A logical name is a name equated to an equivalence string or to a list of 
equivalence strings. When you define a logical name, you equate one character 
string to an equivalence string, which is usually a full or partial file 
specification, another logical name, or any other character string. Once you 
equate a logical name to one or more equivalence strings, you can use the logical 
name to refer to those equivalence strings. For example, you might assign a 
logical name to your default disk and directory. Logical names serve two main 
functions: 

• Shorthand and readability 

You can define commonly used files, directories, and devices with short, 
meaningful logical names. Such names are easier to remember and type than 
the full file specifications. You can define names that you use frequently in 
your login command procedure. A system manager can define names that 
most users on your system use frequently in the site-specific system startup 
command procedure. 

• File independence 

You can use logical names to keep your programs and command procedures 
independent of physical file specifications. For example, if a command 
procedure references the logical name ACCOUNTS, you can equate 
ACCOUNTS to any file on any disk before executing the command procedure. 

Chapter 13 contains information about logical name tables and describes how to 
use logical names. 

1.12 Symbols 

Entering DCL command lines that include parameters, multiple qualifiers, and 
values can make for much typing and can be time-consuming. To simplify your 
interaction with DCL and to save time, you can establish symbols to use in place 
of command names and entire command strings you type frequently. A symbol 
is a name that represents a numeric, character, or logical value. When you use 
a symbol in a DCL command line, DCL uses the value you assign to the symbol. 
By defining a symbol as a command line, you can execute the command by typing 
only the symbol name. 

You can also use symbols in command procedures to collect, store, and manipulate 
certain types of data. 

Chapter 14 describes how to use symbols in DCL commands and command 
procedures. 
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1.13 Command Procedures 

A command procedure is a file that contains a series of DCL commands. Some 
simple command procedures might contain only one or two DCL commands; 
complex command procedures can function as sophisticated computer programs. 
When a command procedure is executed, the DCL interpreter reads the file and 
executes the commands it contains. 

If your system manager has set up a system login command procedure, it is 
executed when you log in. A system login command procedure lets your system 
manager ensure that certain commands are always executed when you and other 
users on the system log in. 

After executing the system login command procedure, the system executes your 
personal login command procedure, if one exists. Your personal login command 
procedure lets you customize your computing environment. The commands 
contained in it are executed every time you log in. When you log in, the system 
automatically executes up to two login command procedures (the systemwide 
login command procedure, and your own login command procedure if it exists). 

The person who sets up your account might have placed a login command 
procedure in your top-level directory. If a login command procedure is not in your 
top-level directory, you can create one yourself, name it LOGIN.COM and place 
it in your top-level directory. Unless your system manager tells you otherwise, 
theLOGIN.COM file that you create will be executed when you login. A sample 
personal login command procedure is described in Chapter 15. 

Appendix C contains several complete command procedures. 

1.14 Lexical Functions 

Lexical functions return information to a command line or command procedure. 
The information returned can be about your process, the system, files and devices, 
logical names, strings, or data types. Lexical functions are identified by the prefix 
F $■ 

You can use lexical functions in any context in which you normally use symbols 
or expressions. In command procedures, you can use lexical functions to translate 
logical names, perform character string manipulations, and determine the current 
processing mode of the procedure. 

Chapter 16 describes how to use lexical functions to obtain and manipulate 
information within a command procedure. 

1.15 Processes and Programs 

The system obtains the characteristics that are unique to your process from the 
user authorization file (UAF ). The UAF lists those users permitted to access 
the system and defines the characteristics for each user's process. The system 
manager usually maintains the UAF. It is within your process that the system 
executes your programs (also called images or executable images) one at a time. 

A process can be a detached process (a process that is independent of other 
processes) or a subprocess (a process that is dependent on another process for 
its existence and resources). Your main process, also called your parent process, 
is a detached process. 

Chapter 17 describes how to use processes to perform computing tasks. 
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A program, also called an image or an executable image, is a file that contains 
instructions and data in machine-readable format. Some programs are associated 
with and invoked by a DCL command. For example, when you type the DCL 
command COPY, the system executes the program SYS$SYSTEM :COPY.EXE. 
Some programs are invoked by entering the DCL command RUN followed by the 
program name. 

I mage files can be supplied by the operating system or by you and usually have a 
file type .EXE. You cannot examine an image file with the DCL commands TYPE, 
PRI NT, or EDIT because image files do not consist of ASCII characters. (Text 
files contain ASCII characters, which are a standard method of representing the 
alphabet, punctuation marks, numerals, and other special symbols.) 

Chapter 17 contains more information about using programs. 

1.16 System Security 

Each system site has unique security requirements. For this reason, every site 
should have a system security policy that outlines physical and software security 
requirements for system managers and users. The OpenVMS Guide to System 
Security describes the security features available with the operating system and 
the tasks that system managers can perform to maintain account and system 
security. 

To ensure system security, the OpenVMS operating system controls both access 
to the system and access to any object that contains shareable information. 

These objects, such as devices, volumes, logical name tables, files, and queues, 
are known as protected objects. All protected objects list a set of access 
requirements that specify who has a right to access the object in a given manner. 

Chapter 2 describes password management and account security. Chapter 4 
and Chapter 5 describe how users can protect their files and directories from 
unauthorized access. Chapter 18 describes general security issues such as 
controlling access to protected objects and accessing data on remote systems. 
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Getting Started: Interacting with the Open VMS 

Operating System 


This chapter describes the following basic tasks you use to interact with the 
OpenVMS operating system: 

• L oggi ng i n to the system 

• Logging in to a remote node 

• Changing your password 

• Recognizing system responses 

• Getting help about the system 

• E ndi ng a remote session 

• L oggi ng out of the system 

The way you log in to and log out of the OpenVMS operating system depends on 
how the system is set up at your site. This section provides a general description 
of logging in to and out of the operating system. Check with your system 
manager for the procedures specific to your site. 

2.1 Logging In to the System 

You need two pieces of information to log in to the system: a user name and a 
password. Your system manager usually sets up accounts and gives you a user 
name and initial password (see Section 2.2.1). 

To log in to the system, use the following procedure: 

1. Make sure your terminal is plugged in and the power is turned on. 

2. Press the Return key to signal the system that you want to log in. (You might 
need to press Return several times.) 

The system displays a prompt for your user name: 

Username : 

3. Enter your user name and press Return. (You have approximately 30 seconds 
to do this; otherwise, the system "times out." If a timeout occurs, you must 
start the login procedure again.) 

The system displays your user name on the screen as you type it. For 
example: 

Username: CASEY [Return] 

The system prompts you for your password: 

Password: 
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4. Enter your password and press Return. The system does not display your 
password, which is sometimes referred to as "no echo." 

5. Depending on how your system manager has set up your account, you might 
be required to enter a second password or use an automatically generated 
password (see Section 2.2.3). 

The following example shows a successful login: 

| Return] 

Username: CASEY | Return | 

Password: | Return I 

Welcome to OpenVMS on node MARS 
Last interactive login on Friday, ll-DEC-1994 08:41 
Last non-interactive login on Thursday, 10-DEC-1994 11:05 

$ 

If you make a mistake entering your user name or password or if your password 
has expired, the system displays the message "User authorization failure," and 
you are not logged in. If you make a mistake, press Return and try again. If 
your password has expired, you need to change your password; the system will 
automatically display the Set Password: prompt. See Section 2.6 for information 
on changing your password in this instance. If you have any other problems 
logging in, get help from the person who set up your account. 

If your login is successful, the system displays a dollar sign ($) in the left margin 
of your screen. The dollar sign symbol is the default DCL prompt; it indicates 
that the system is ready to use. 

2.2 Choosing a Password for Your Account 

To choose a secure password, use the following guidelines: 

• Include both numbers and letters in the password. Although a 6-character 
password that contains only letters is fairly secure, a 6-character password 
with both letters and numbers is much more secure. 

• Choose passwords that contain 6 to 10 characters. Adequate length makes 
passwords more secure. You can choose a password as long as 32 characters. 

• Do not select passwords from a dictionary or from your native language. 

• Avoid choosing words readily associated with your computer site or yourself, 
such as the name of a product or the model of your car. 

• Choose new passwords each time. Do not reuse old ones. 

Your system manager or security administrator may set up additional restrictions, 
for example, not allowing passwords with fewer than 10 characters or not 
allowing repeats of passwords. 

Table 2-1 provides examples of secure and insecure passwords. 
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Table 2-1 Examples of Secure and Insecure Passwords 


Secure Passwords 

Insecure Passwords 

Nonsense syllables: 

Words with a strong personal association: 

aladaskgam 

your name 

eojfuvcue 

the name of a loved one 

joxtyois 

the name of your pet 
the name of your town 
the name of your automobile 

A mixed string: 

A work-related term: 

492 weid 

your company name 

$924spa 

a special project 

zu_$rags 

your work group name 


2.2.1 Obtaining Your Initial Password 

Typically, when you learn that an account has been created for you on the system, 
you are told whether a user password is required. If user passwords are in effect, 
your system manager will usually assign a specific password for your first login. 
This password has been placed in the system user authorization file (UAF) with 
other information about how your account can be used. 

It is inadvisable to have passwords that others could easily guess. Ask the person 
creating the account for you to specify a password that is difficult to guess. If you 
have no control over the password you are given, you might be given a password 
that is the same as your first name. If so, change it immediately after you log in. 
(The use of first or last names as passwords is a practice so well known that it is 
undesirable from a security standpoint.) 

Log in to your account soon after it is created to change your password. If there 
is a time lapse from the moment your account is created until your first login, 
other users might log in to your account successfully, gaining a chance to damage 
the system. Similarly, if you neglect to change the password or are unable to do 
so, the system remains vulnerable. Possible damage depends largely on what 
other security measures are in effect. 

At the time your account is created, you should also be told a minimum length for 
your password and whether you can choose your new password or whether the 
system generates the password for you. 

2.2.2 Observing System Restrictions on Passwords 

The system screens passwords for acceptability, as follows: 

• It automatically compares new passwords to a system dictionary. This helps 
to ensure that a password is not a native language word. 

• It maintains a history list of your old passwords and compares each new 
password to this list to be sure that you do not reuse a password. 

• It enforces a minimum password length, which the system manager specifies 
in your UAF record. 

The system rejects any passwords that it finds in a system dictionary, that you 
have used before, and that are shorter than the minimum password length 
specified in your UAF. 
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2.2.3 Knowing What Type of Password to Use 

There are several types of passwords recognized by the OpenVMS operating 
system. In general, you need to provide a user password when you log in. In 
some cases, you might also need to provide a system password to gain access 
to a particular terminal before logging in with your user password. If you are 
using a system with high security requirements, you might need to provide a 
primary password and a secondary password. Table 2-2 describes each type 
of password. 


Table 2-2 Types of Passwords 


Password 

Description 

User password 

Required for most accounts. After entering your user name, 
you are prompted for a password. If the account requires 
both primary and secondary passwords, two passwords must 
be entered. 

System password 

Controls access to particular terminals and is required at the 
discretion of the security administrator. System passwords 
are usually necessary to control access to terminals that 
might be targets for unauthorized use, such as dialup and 
public terminal lines. 

Primary password 

The first of two passwords to be entered for an account 
requiring both primary and secondary passwords. 

Secondary password 

The second of two passwords to be entered for an account 
requiring both primary and secondary passwords. The 
secondary password provides an additional level of security 
on user accounts. Typically, the primary user does not know 
the secondary password; a supervisor or other key person 
must be present to supply it. For certain applications, the 
supervisor may also decide to remain present while the 
account is in use. Thus, secondary passwords facilitate 
controlled logins and the actions taken after a login. 


Secondary passwords can be time-consuming and 
inconvenient. They arejustified only at sites with maximum 
security requirements. An example of an account that 
justifies dual passwords would be one that bypasses normal 
access controls to permit emergency repair to a database. 


2.2.4 Entering a System Password 

Your security administrator will tell you if you must specify a system password to 
log in to one or more of the terminals designated for your use. Ask your security 
administrator for the current system password, how often it changes, and how to 
obtain the new system password when it does change. 

To specify a system password, do the following: 

1. Press the Return key until the terminal responds with the recognition 
character, which is normally a bell. 

| Return] 

<bell> 

2. Enter the system password and press Return. 

| Return | 
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As this example shows, there is no prompt and the system does not display 
the characters you type. If you fail to specify the correct system password, 
the system does not notify you. (I nitially, you might think the system is 
malfunctioning unless you know that a system password is required at that 
terminal.) If you do not receive a response from the system, assume that you 
have entered the wrong password and try again. 

3. When you enter the correct system password, you receive the system 

announcement message, if there is one, followed by the Username: prompt. 
For example: 

MAPLE - A member of the Forest Cluster 
Unauthorized Access is Prohibited 

Username : 

2.2.5 Entering a Secondary Password 

Your security administrator decides whether to require the use of secondary 
passwords for your account at the time your account is created. When your 
account requires primary and secondary passwords, you need two passwords to 
log in. Minimum password length, which the security administrator specifies in 
your UAF, applies to both passwords. 

An example of a login requiring primary and secondary passwords follows: 


WILLOW - A member of the Forest Cluster 
Welcome to OpenVMS on node WILLOW 

Username: RWOODS 

Password: I Return | 

Password: | Return I 

Last interactive login on Friday, ll-DEC-1994 10:22 

$ 

As with a single password login, the system allots a limited amount of time for 

the entire login. If you do not enter a secondary password in time, the login 

period expires. 

2.2.6 Password Requirements for Different Types of Accounts 

Four types of user accounts are available on OpenVMS systems: 

• Accounts secured with passwords that you or the security administrator 
change periodically. This account type is the most common. 

• Accounts that always require passwords but prohibit you from changing the 
password. By locking the password (setting the LOCKPWD flag in the UAF), 
the security administrator controls all changes made to the password. 

• Restricted accounts limit your use of the system and sometimes require a 
password. 

• Open accounts require no password. When you log in to an open account, 
the system does not prompt you for a password and you do not need to enter 
one. You can begin entering commands immediately. Because open accounts 
allow anyone to gain access to the system, they are used only at sites with 
minimal security requirements. 
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2.3 Reading Informational Messages 

When you log in from a terminal that is directly connected to a computer, 
the OpenVMS system displays informational system messages. Example 2-1 
illustrates most of these messages. 

Example 2-1 Local Login Messages 


WILLOW - A member of the Forest Cluster 1 

Unlawful Access is Prohibited 

Username: RWOODS 
Password: 

You have the following disconnected process: 2 

Terminal Process name Image name 

VTA52 : RWOODS (none) 

Connect to above listed process [YES] : NO 

Welcome to OpenVMS on node WILLOW 3 

Last interactive login on Wednesday, ll-DEC-1994 10:20 4 
Last non-interactive login on Monday, 30-NOV-1994 17:39 5 
2 failures since last successful login 6 

You have 1 new mail message. 7 


$ 


1 The announcement message identifies the node (and, if relevant, the 
VMScluster name). It may also warn unauthorized users that unlawful 
access is prohibited. The system manager or security administrator can 
control both the appearance and the content of this message. 

2 A disconnected process message informs you that your process was 
disconnected at some time after your last successful login but is still 
available. You have the option of reconnecting to the old process which 
returns your process to its state before you were disconnected. 

The system displays the disconnected job message only when the following 
conditions exist: 

• The terminal where the interruption occurred is set up as a virtual 
terminal. 

• Your terminal is set up as one that can be disconnected. 

• During a recent session, your connection to the central processing unit 
(CPU) through that terminal was broken before you logged out. 

I n general, the security administrator should allow you to reconnect to a 
disconnected job because this ability poses no special problems for system 
security. However, the security administrator can disable this function by 
changing the setup on terminals and by disabling virtual terminals on the 
system. (For information on setting up and reconnecting to virtual terminals, 
refer to the OpenVMS System Manager's Manual.) 

3 A welcome message indicates the version number of the OpenVMS operating 
system that is running and the name of the node on which you are logged 
in. The system manager can choose a different message or can suppress the 
message entirely. 
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4 The last successful interactive login message provides the time of the last 
completed login for a local, dialup, or remote login. (The system does not 
count logins from a subprocess whose parent was one of these types.) 

5 The last successful noninteractive login message provides the time the last 
noninteractive (batch or network) login completed. 

6 The number of login failures message indicates the number of failed attempts 
at login. (An incorrect password is the only source of login failure that is 
counted.) To attract your attention, a bell rings after the message appears. 

7 The new mail message indicates if you have any unread mail messages. 

A security administrator can suppress the announcement and welcome messages, 
which include node names and operating system identification. Because login 
procedures differ according to operating system, it is more difficult to log in 
without this information. 

The last login success and failure messages are optional. Your security 
administrator can enable or disable them as a group. Sites with medium- 
level or high-level security needs display these messages because they can 
indicate break-in attempts. In addition, by showing that the system is monitoring 
logins, these messages can be a deterrent to potential illegal users. 

Each time you log in, the system resets the values for the last successful login 
and the number of login failures. If you access your account interactively and do 
not specify an incorrect password in your login attempts, you may not see the last 
successful noninteractive login and login failure messages. 

2.4 Types of Logins and Login Classes 

Logins can be either interactive or noninteractive. When you log in interactively, 
you enter a user name and a password. In noninteractive logins, the system 
performs the identification and authentication for you; you are not prompted for a 
user name and password. 

In addition to interactive and noninteractive logins, the OpenVMS operating 
system recognizes different classes of logins. How you log in to the system 
determines the login class to which you belong. Based on your login class, as 
well as the time of day or day of the week, the system manager controls your 
access to the system. 

2.4.1 Logging In Interactively: Local, Dialup, and Remote Logins 

Interactive logins include the following login classes: 

• Local 

You log in from a terminal connected directly to the central processor or from 
a terminal server that communicates directly with the central processor. 

• Dialup 

You log in to a terminal that uses a modem and a telephone line to make 
a connection to the computer system. Depending on the terminal that your 
system uses, you might need to execute a few additional steps initially. Your 
site security administrator can give you the necessary details. 

• Remote 
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You log in to a node over the network by entering the DCL command SET 
HOST. For example, to access the remote node HUBBUB, you enter the 
following command: 

$ SET HOST HDBBDB 

If you have access to an account on node HUBBUB, you can log in to that 
account from your local node. You have access to the facilities on node 
HUBBUB, but you remain physically connected to your local node. 

For additional information on remote sessions, see Section 2.11.1. 


2.4.2 When the System Logs In for You: Network and Batch Logins 


Non interactive logins include network logins and batch logins. 

The system performs a network login when you initiate a network task on a 
remote node, such as displaying the contents of a directory or copying files stored 
in a directory on another node. Both your current system and the remote system 
must be nodes in the same network. I n the file specification, you identify the 
target node and provide an access control string, which includes your user name 
and password for the remote node. 

For example, a network login occurs when user GREG, who has an account on 
remote node PARI S, enters the following command: 

$ DIRECTORY PARIS "GREG 8G4FR93A" : :W0RK2 : [PUBLIC] *.*; * 

This command displays a listing of all the files in the public directory on disk 
WORK2. It also reveals the password 8G4FR93A. A more secure way to perform 
the same task would be to use a proxy account on node PARI S. For an example of 
a proxy login, see Section 18.3.2. 

The system performs a batch login when a batch job that you submitted runs. 
Authorization to build the job is determined at the time the job is submitted. 
When the system prepares to execute the job, the job controller creates a 
noninteractive process that logs in to your account. No password is required 
when the job logs in. 


2.5 Login Failures: When You Are Unable to Log In 


Logins can fail for any number of reasons. One of your passwords might have 
changed or your account might have expired. You might be attempting to log in 
over the network or from a modem but be unauthorized to do so. The following 
table summarizes common reasons for login failure: 


Failure Indicator: 


Reason: 


No response from the terminal 


A defective terminal, a terminal that 
requires a system password, or a terminal 
that is not powered on. 


No response from any terminal 

No response from the terminal when you 
enter the system password 

System messages: 


The system is down. 


The system password changed. 
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Failure Indicator: Reason: 


"User authorization failure" 

"Not authorized to log in from this source" 

"Not authorized to log in at this time" 

"User authorization failure" (and no known 
user failure occurred) 


A typing error in your user name or 
password. 

The account or password expired. 

Your particular class of login (local, dialup, 
remote, interactive, batch, or network) is 
prohibited. 

You do not have access to log in during this 
hour or this day of the week. 

An apparent break-in has been attempted 
at the terminal using your user name, and 
the system has temporarily disabled all 
logins at that terminal by your user name. 


The following sections describe the reasons for login failure in more detail. 

2.5.1 Using a Terminal That Requires a System Password 

You cannot log in if the terminal you attempt to use requires a system password 
and you are unaware of the requirement. All attempts at logging in fail until you 
enter the system password. 

If you know the system password, perform the steps described in Section 2.2.4. If 
your attempts fail, it is possible that the system password has been changed. If 
you do not know the system password and you suspect that this is the problem, 
try to log in at another terminal or request the new system password. 

2.5.2 Observing Your Login Class Restrictions 

If you attempt a class of login that is prohibited in your UAF record, your login 
will fail. For example, your security administrator can restrict you from logging 
in over the network. If you attempt a network login, you receive a message tel I i ng 
you that you are not authorized to log in from this source. 

Your security administrator can restrict your logins to include or exclude any of 
the following classes: local, remote, dialup, batch, or network. (For a description 
of these classes, see Section 2.4.1 and Section 2.4.2.) 

2.5.3 Using an Account Restricted to Certain Days and Times 

Another cause of login difficulty is failure to observe your shift restrictions. 

A system manager or security administrator can control access to the system 
based on the time of day or the day of the week. These restrictions are imposed 
on classes of logins. The security administrator can apply the same work-time 
restrictions to all classes of logins or choose to place different restrictions on 
different login classes. If you attempt a login during a time prohibited for that 
login class, your login fails. The system notifies you that you are not authorized 
to log in at this time. 

When shift restrictions apply to batch jobs, jobs you submit that are scheduled 
to run outside your permitted work times are not run. The system does not 
automatically resubmit such jobs during your next available permitted work time. 
Similarly, if you have initiated any kind of job and attempt to run it beyond your 
permitted time periods, the job controller aborts the uncompleted job when the 
end of your allocated work shift is reached. This job termination behavior applies 
to all jobs. 
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2.5.4 Failing to Enter the Correct Password During a Dialup Login 

Your security administrator can control the number of opportunities you are 
given to enter a correct password during a dialup login before the connection is 
automatically broken. 

If your login fails and you have attempts remaining, press the Return key and try 
again. You can do this until you succeed or reach the limit. If the connection is 
lost, you can redial the access line and start again. 

The typical reason for limiting the number of dialup login failures is to discourage 
unauthorized users attempting to learn passwords by trial and error. They 
already have the advantage of anonymity because of the dialup line. Of course, 
limiting the number of tries for each dialup does not necessarily stop this kind 
of break-in attempt. It only requires the perpetrator to redial and start another 
login. 

2.5.5 Knowing When Break-In Evasion Procedures Are In Effect 

If anyone has made a number of failed attempts to log in at the same terminal 
with your user name, the system can respond as though a break-in attempt is 
in progress. That is, the system concludes that someone is attempting to gain 
illegal access to the system by using your user name. 

At the discretion of your security administrator, break-in evasion measures can 
be in effect for all users of the system. The security administrator controls how 
many password attempts are allowed over what period of time. Once break-in 
evasion tactics are triggered, you cannot log in to the terminal— even with your 
correct password— during a defined interval. Your security administrator can tell 
you how long you must wait before reattempting the login, or you can move to 
another terminal to attempt a login. 

If you suspect that break-in evasion is preventing your login and you have not 
personally experienced any login failures, contact your security administrator 
immediately. Together, you should attempt another login and check the message 
that reveals the number of login failures since the last login to confirm or deny 
your suspicion of break-in attempts. (If your system does not normally display 
the login message, your security administrator can use the Authorize utility 
(AUTHORIZE) to examine the data in your UAF record.) With prompt action, 
your security administrator can locate someone attempting logins at another 
terminal. 

2.6 Changing Your Password 

Changing passwords on a regular basis promotes system security. To change your 
password, enter the DCL command SET PASSWORD. 

The system manager can allow you to select a password on your own or can 
require that you use the automatic password generator when you change your 
password. If you select your own password, note that the password must follow 
system restrictions on length and acceptability (see Section 2.2.2). For example, 
if your password choice is too short, the system displays the following message: 

%SET-E-INVPWDLEN, invalid password length - password not changed 

Section 2.2.6 provides guidelines and examples for specifying secure passwords. 

There is no restriction on how many times you can change your password in a 
given period of time. 
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2.6.1 Selecting Your Own Password 

If your system manager does not require use of the automatic password generator, 
the SET PASSWORD command prompts you to enter the new password. It then 
prompts you to reenter the new password for verification, as follows: 

$ SET PASSWORD [Rejurn] 

New password: I Return I 

Verification: | Return | 

If you fail to enter the same new password twice, the password is not changed. 

If you succeed in these two steps, there is no notification. The command changes 
your password and returns you to the DCL prompt. 

Even though your security administrator might not require the password 
generator, you are strongly encouraged to use it to promote the security of 
your system. Section 2.6.2 describes how to use generated passwords. 

2.6.2 Using Generated Passwords 

If your system security administrator decides that you must let the system 
generate the password for you automatically, the system provides you with a list 
of password choices when you enter the DCL command SET PASSWORD. (If your 
system is not set up to use automatically generated passwords, you can use them 
by specifying the SET PASSWORD command with the /GENERATE qualifier.) 
The character sequence resembles native language words to make it easy to 
remember, but it is unusual enough to be difficult for outsiders to guess. Because 
system-generated passwords vary in length, they become even more difficult to 
guess. 


Note 

The password generator uses basic syllabic rules to generate words but 
has no real knowledge of any language. As a result, it can unintentionally 
produce words that are offensive. 


I n the following example, the system automatically generates a list of passwords 
made up of random sequences of characters. The minimum password length 
for the user in the following example has been set to 8 characters in their UAF 
record. 


$ SET PASSWORD 

old password: I Return I 1 


reankuna 

cigtawdpau 

adehecun 

ceebatorai 

arhoajabad 


rean-ku-na 2 
cig-tawd-pau 
a-de-he-cun 
cee-ba-to-rai 
ar-hoa- ja-bad 


Choose a password from this list, or press Return to get a new list 3 
New password: | Return | 4 

Verification: | Return | 5 

S 6 


The preceding example illustrates the following: 

i The user correctly specifies the old password and presses the Return key. 
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2 The system responds with a list of five password choices ranging in length 
from 8 to 10 characters. Usually, the password that is easiest to pronounce is 
easiest to remember; therefore, it is the best choice. 


On OpenVMS VAX systems, representations of the same word divided into 
syllables are displayed to the right of each password choice (as shown here)> 


3 The system informs the user that it is possible to request a new list by 
pressing the Return key in response to the prompt for a new password. 


4 The user enters one of the first five possible passwords and presses the 
Return key. 


5 The system recognizes that this password is one provided by the automatic 
password generator and responds with the verification prompt. The user 
enters the new password again and presses Return. 


6 The system changes the password and responds with the DCL prompt. 


One disadvantage of automatic password generation is the possibility that you 
might not remember your password choice. However, if you dislike all the 
password choices in your list or think none are easy to remember, you can always 
request another list. 


A more serious drawback of automatic password generation is the potential 
disclosure of password choices from the display the command produces. To 
protect your account, change your password in private. If you perform the change 
on a video terminal, clear the display of password choices from the screen after 
the command finishes. If you use a printing terminal, properly dispose of all 
hardcopy output. 


If you later realize that you failed to protect your password in these ways, change 
your password immediately. Depending on site policy or your own judgment 
concerning the length of time your account was exposed, you should notify your 
security administrator that a security breach could have occurred through your 
account. 


2.6.3 Changing a Secondary Password 

To change a secondary password, use the DCL command SET PASSWORD 
/SECONDARY. You are prompted to specify the old secondary password and 
the new secondary password, just as in the procedure for changing the primary 
password. To remove a secondary password, press the Return key when you are 
prompted for a new password and verification. 

You can change primary and secondary passwords independently, but both are 
subject to the same change frequency because they share the same password 
lifetime. 


2.6.4 Changing Your Password as You Log In 

Even if your current password has not yet expired, you can change your password 
when you log in to the system by including the/NEW_PASSWORD qualifier with 
your user name, as follows: 
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WILLOW - A member of the Forest Cluster 

Username: RW00DS/NEW_PASSW0RD 
Password: 

Welcome to OpenVMS on node WILLOW 

Last interactive login on Tuesday, 7-NOV-1994 10:20 
Last non-interactive login on Monday, 6-NOV-1994 14:20 

Your password has expired; you must set a new password to log in 
New password: 

Verification: 

When you enter the /NEW_PASSWORD qualifier after your user name, the 
system prompts you to set a new password immediately after login. 

2.7 Password and Account Expiration Times 

Your system manager can set up your account so that your password, or the 
account itself, expires automatically on a particular date and time. Password 
expiration times promote system security by forcing you to change your password 
on a regular basis. Account expiration times help to ensure that accounts are 
available only for as long as they are needed. 

2.7.1 Changing an Expired Password 

As you approach the expiration time of your password, you receive an advance 
warning message. The message first appears 5 days before the expiration date 
and at each subsequent login. The message appears immediately below the new 
mail message and sounds the bell character on your terminal to attract your 
attention. The message indicates that your password is expiring, as follows: 

WARNING — Your password expires on Thursday ll-DEC-1994 15:00 

If you fail to change your password before it expires, you receive the following 
message when you log in: 

Your password has expired; you must set a new password to log in 
New password: 

The system prompts you for a new password or, if automatic password generation 
is enabled, asks you to select a new password from those listed (see Section 2.6.2). 
You can abort the login by pressing Ctrl/Y. At your next login attempt, the system 
again prompts you to change your password. 

When You Are Using a Secondary Password 

If secondary passwords are in effect for your account (see Section 2.2.3), the 
secondary password expires at the same time as the primary one. You are 
prompted to change both passwords. If you change the primary password and 
press Ctrl/Y before changing the secondary password, the login fails. The system 
does not record a password change. 

When You Fail to Change Your Password 

If the system manager decides not to force you to change your expired password 
upon logging in, you receive one final warning when you log in after your 
password expires, as follows: 

WARNING — Your password has expired; update immediately with 
SET PASSWORD! 

At this point, if you do not change the password or if the system fails before you 
have the opportunity to do so, you will be unable to log in again. To regain access, 
see your system manager. 
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2.7.2 Renewing an Expired Account 

If you need your account for a specific purpose for a limited time only, the person 
who creates your account may specify a period of time after which the account 
lapses. For example, student accounts at universities are typically authorized for 
a single semester at a time. 

Expired accounts deny logins automatically. You receive no advance warning 
message before the account expiration date, so it is important to know in advance 
your account duration. The account expiration resides in the UAF record, which 
can be accessed and displayed only through the use of the OpenVMS Authorize 
utility (AUTFIORIZE) by users with the SYSPRV privilege or equivalent— 
normally, your system manager or security administrator. 

When your account expires, you receive an authorization failure message at your 
next attempted login. If you need an extension, follow the procedures defined at 
your site. 

2.8 Guidelines for Protecting Your Password 

Illegal system accesses involving the use of a correct password are more often 
traced to disclosure of the password by its owner than to surreptitious discovery. 
It is vital that you do not reveal your password to anyone. 

You can best protect your password by observing the following rules: 

• Select reasonably long passwords that cannot be guessed easily. Avoid using 
words in your native language that appear in a dictionary. Consider including 
numbers in your password. Alternatively, let the system generate passwords 
for you automatically. 

• Never write down your password. 

• Never give your password to another user. If another user obtains your 
password, change it immediately. 

• Do not include your password in any file, including the body of an electronic 
mail message. (If anyone else reveals a password to you, delete the 
information promptly.) 

The character strings that appear in conjunction with your actual password 
can make it easy for someone to find your password in a file. For example, a 
quotation mark followed by two colons always comes after a user name 
and password i n an access control stri ng. Someone attempti ng to break i nto 
the system could obtain your password by searching inadequately protected 
files for this string. Another way in which you might reveal your password is 
by using the word “password” in a text file, for example: 

My password is GOBBLEDYGOOK. 

• If you submit a batch job on cards, do not leave your password card where 
others may be able to obtain your password from it. 

• Do not use the same password for accounts on different systems. 

An unauthorized user can try one password on every system where you have 
an account. The account that first reveals the password might hold little 
information of interest, but another account might yield more information or 
more privileges, ultimately leading to a far greater security breach. 
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• Before you log in to a terminal that is already on, invoke the secure terminal 
server feature (if enabled) by pressing the Break key. This is particularly 
relevant when you are working in a public terminal room. 

A password grabber program is a special program that displays an empty 
video screen, a screen that appears to show the system has just been 
initialized after a crash, or a screen that shows a nonexistent logout. When 
you attempt to log in, the program runs through the normal login sequence 
so you think you are entering your user name and password in a normal 
manner. However, once the program receives this key information and passes 
it on to the perpetrator, it displays a login failure. You might think you 
mistyped your password and be unaware that you have just revealed it to 
someone else. 

To eliminate this possibility, your security administrator might advise you to 
press the Break key before logging in. Pressing the Break key invokes the 
secure terminal server feature for the terminal, if it has been enabled by 
the security administrator. The secure server ensures that the OpenVMS 
login program is the only program able to receive your login. 

• Unless you share your password, change it every 3 to 6 months. Digital 
warns against sharing passwords. If you do share your password, change it 
every month. 

• Change your password immediately if you have any reason to suspect it might 
have been discovered. Report such incidents to your security administrator. 

• Do not leave your terminal unattended after you log in. 

You might think the system failed and came back up again, when actually 
someone has loaded a password-stealing program. Even a terminal that 
displays an apparently valid logout message might not reflect a normally 
logged out process. 

• Check your last login messages routinely. The password-stealing program 
cannot actually increase the login failure count, although it looks like a 
login failure to you. Be alert for login failure counts that do not appear 
following your failure or that are one less than the number you experienced. 

If you observe this or any other unusual failure during a login, change your 
password immediately and notify your security administrator. 

2.9 Recognizing System Responses 

The system responds to the commands you enter in one or more of the following 

ways: 

• By executing the command. Generally, you know your command has executed 
successfully when the system prompt returns (by default, the dollar sign). 

• By executing the command and informing you in a message what it has done. 

• By informing you of errors, if execution of a command is unsuccessful. 

• By supplying values (defaults) you have not supplied. 
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Understanding Defaults 

A default is the value supplied by the operating system when you do not specify 
one yourself. For example, if you do not specify the number of copies as a 
qualifier for the PRINT command, the system uses the default value 1. The 
operating system supplies default values in several areas, including command 
qualifiers and parameters. The defaults that the operating system uses with 
specific commands are described in each command’s entry in the OpenVMS DCL 
Dictionary. 

Looking at Informational System Messages 

The system responds to some commands by displaying information in a system 
message about what it has done. For example, when you use the PRINT 
command, the system displays the job identification number it assigned to the 
print job and shows the name of the print queue the job has entered. 

$ PRINT MYFILE . LIS [Return] 

Job MYFILE (queue SCALE_PRINT, entry 210) started on SYS$PRINT 

Not all commands display informational messages. Successful completion of 
a command is usually indicated when the DCL prompt returns. Unsuccessful 
completion is always indicated by one or more error messages. 

Looking at System Error Messages 

If you enter a command incorrectly, the system displays a system message and 
prompts you for the correct command string, as the following example shows: 

$ CAPY | Return | 

%DCL-W-IWERB, unrecognized command verb - check validity and spelling 
\CAPY\ 

$ 

The format for the 3-part code is: 

DCL-W-IVVERB 

where: 

DCL The OpenVMS facility or component name that returned the error. In this 

example, the message is from DCL, the default command interpreter. 

W A severity level that indicates a warning. Other severity levels include S 

(success), I (information), E (error), and F (fatal or severe error). 

I VVERB The type of message. The message can be identified by the mnemonic 

IVVERB in the OpenVMS system messages documentation or by using the 
Help Message utility (MSGH LP) described in Section 2.10.2. 

You can also receive system error messages during command execution if the 
system cannot perform the function you have requested. For example, if you type 
a PRI NT command correctly but the file you specify does not exist, the PRI NT 
command informs you of the error with a message like the following: 

$ PRINT NOFILE.DAT [Return] 

%PRINT-E-OPENIN, error opening CLASS1: [MAYMON] NOFILE. DAT; as input 
-RMS-E-FNF, file not found 
$ 

The first message is from the PRI NT command. It tells you it cannot open the 
specified file. The second message indicates the reason for the first; that is, the 
file cannot be found. RMS refers to the OpenVMS file-handling software, Record 
Management Services; error messages related to file-handling are generally 
OpenVMS RMS messages. 
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Checking Your Current Process 

If you suspect that your process is not doing what you think it should be doing, 
press Ctrl/T. Ctrl/T displays a single line of statistical information about the 
current process. The statistical information includes node and user name, current 
time, current process, central processing unit (CPU) usage, number of page 
faults, level of I/O activity, and memory usage, which is listed in number of 
CPU -specific pages. 

When you press Ctrl/T during an interactive terminal session, it momentarily 
interrupts the current command, command procedure, or image to display 
statistics. Although Ctrl/T disrupts the characters on the screen, it does not affect 
any procedure or editing session. For example, if a user named MCCARTHY on 
node GREEN presses Ctrl/T while using the EVE editor, the following line is 
displayed in the EVE message window: 

GREEN: : MCCARTHY 13:45:02 EVE CPU=00 : 00 : 03 . 33 PF=778 10=295 MEM=315 

To refresh the screen, press Ctrl/W. 

Ctrl/T is disabled by default. If you know your system is running and Ctrl/T 
does not display statistical information, you can enable Ctrl/T with the DCL 
command SET CONTROL=T. Enter the command at DCL level (at the dollar sign 
($) prompt), then press Ctrl/T again. Ctrl/T will remain in effect for the duration 
of your process, unless it is disabled from a program or command such as SET 
NOCONTROL =T. Note that your terminal must be set to BROADCAST mode 
for Ctrl/T to display on your screen. To set your terminal to BROADCAST mode, 
enter the DCL command SET TERMI NAL/BROADCAST at the DCL prompt. 

2.10 Getting Help About the System 

When you are logged in to the operating system, you can obtain information 
about using the system and available commands by using the HELP command. 
You can also get help on system messages by entering the HELP/MESSAGE 
command as shown in Section 2.10.2. 

2.10.1 Getting Help on OpenVMS Commands and Utilities 

Use the following procedure to get help on OpenVMS commands and utilities: 

1. Enter HELP at the DCL prompt and press Return: 

$ HELP | Return | 

HELP displays a list of topics and the Topic? prompt. 

HELP 

. (HELP message text and subtopics) 

Topic? 

2. To see information about one of the topics, type the topic name after the 
prompt and press Return. 

Topic? SHOW USERS [RitEE] 
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HELP displays the following information: 

SHOW 


USERS 


Displays the user name and node name (in a VAXcluster environment) 
of interactive, subprocess, and batch users on the system. 

Format 

SHOW USERS [username] 

Additional information available: 

PARAMETER QUALIFIER 

/BATCH /CLUSTER /FULL /INTERACTIVE /NETWORK /NODE 

/OUTPUT /SUBPROCESS 

Examples 

SHOW USERS Subtopic? 

3. If you want information on one of the subtopics, type the name after the 
prompt and press Return. 

SHOW USERS Subtopic? Examples | Return | 

HELP displays information about that subtopic. 

Examples 

. (SHOW USERS Examples message text and subtopics, if any) 

To redisplay the SHOW USERS topic and the list of subtopics, enter a 
question mark (?) at the SHOW USERS Subtopic? prompt. If you want to 
read all of the listed subtopics, enter an asterisk (*). 

4. If you want information on another topic, press Return. Help displays the 
Topic? prompt. 

5. To exit Help, press Return until you return totheDCL prompt. 

If you know the command you need information about, enter HELP and the 
command name. For example, to get help about the SHOW USERS command 
enter the following command: 

$ HELP SHOW USERS [RiiUiUI 

If you need help but do not know what command or system topic to specify, enter 
the command HELP with the word HINTS as a parameter. Each task name 
listed in the HINTS text is associated with a list of related command names and 
system information topics. 

The OpenVMS DCL Dictionary contains more information about the HELP 
command. 

2.10.2 Getting Help on System Messages 

Use the Help Message utility (MSGHLP) to get online help for system messages. 
To display information on how the last command completed, type: 

$ HELP/MESSAGE 

You can also display information about a specific message by including the 
message identifier or words from the message text. For example: 

$ HELP/MESSAGE BADACP 
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A message and its description can also be accessed by entering the message 
status code. For example: 

$ HELP/MESSAGE/STATUS=%X00038090 [Return] 

If you do not know the message status code, you can view it by entering the 
command SHOW SYMBOL followed by the $STATUS global symbol. For 
example: 

S SHOW SYMBOL $STATUS 
SSTATUS == "%X00038090" 

The Help Message utility allows you to update the messages database with your 
own messages or to add comments to existing message descriptions. You can 
also extract a subset of messages from the messages database to create and print 
your own customized messages documentation. For details on how to use the 
Help Message utility, see OpenVMS System Messages: Companion Guide for Help 
Message Users. 

2.11 Logging Out of the System 

When you finish using the system, always log out. This prevents unauthorized 
users from accessing your account and the system. It is also a wise use of system 
resources; the resources you no longer need are available for other users. 

To log out, enter LOGOUT at the DCL prompt. For example: 

$ LOGOUT | Return | 

The system displays a message, similar to the following message, confirming that 
you are logged out of the system: 

$ LOGOUT | Return | 

HARRIS logged out at ll-DEC-1994 12:42:48.12 


Note 

You can log out of the system only when you are at the DCL prompt 
($). You cannot enter the LOGOUT command while you are compiling 
or executing a program, using a text editor (such as EDT or EVE), or 
running a utility (such as Mail). First you must exit the program, editor, 
or utility. When the system displays the DCL prompt, you can log out. 


To find out how much time you spent at the terminal (elapsed time), how much 
computer time you used (charged CPU time), and other accounting information, 
enter LOGOUT/FULL at the DCL prompt. For example: 

S LOGOUT/FULL [Return] 

The system displays information similar to the following: 


SIMPSON logged out at ll-DEC-1994 

Accounting information: 

Buffered I/O count: 8005 

Direct I/O count: 504 

Page faults: 1476 

Charged CPU time:0 00:00:50.01 


12:42:48.12 


Peak working set size: 212 
Peak virtual size: 770 
Mounted volumes: 0 
Elapsed time:0 02:27:43.06 
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2.11.1 Ending a Remote Session 

You can end a remote session in two ways: 

• Use the remote system's logout procedure (for example, on an OpenVMS 
system, use the LOGOUT command). 

• Press Ctrl/Y twice to obtain the host system's prompt, which asks whether 
you want to abort the remote session. Answer Y if you want to abort the 
remote session. This method works regardless of the type of system running 
on the remote node. 

When you end a remote session, the system displays the message "%REM-S-END, 
control returned to node NODE NAME::" and returns you to the process on the 
system from which you made the remote node connection. 

If the network connection to a remote system is lost, DECnet will retransmit 
your data in an attempt to reestablish communications. If DECnet is unable 
to reestablish communications within a predetermined timeout period, your 
connection to the remote system is terminated and the system displays the 
message "Path lost to partner". Refer to Section 2.4.1 for additional information 
on remote logins. 

2.11.2 Logging Out Without Compromising System Security 

Logging out of a session conserves system resources and protects your files. 
Leaving a terminal on line represents one of the greatest sources of inside 
break-ins. When you leave your terminal on line and your office open, you have 
effectively given away your password and your privileges and have left your files 
and those of the other members of your group unprotected. Any user can easily 
and quickly transfer all files accessible through your account. A malicious insider 
could rename and delete your files and any other files to which you have write 
access. If you have special privileges, especially privileges in the Files or All 
category, a malicious user can do major damage. 

Log out when you leave your office even for a brief period of time. If you have 
performed remote logins, you must log out of each node. The following sections 
describe security considerations for logging out of specific types of terminals or 
sessions. 

2.11.2.1 Clearing Your Terminal Screen 

You might want to clear your screen each time you log out of a terminal to ensure 
that your user name, node name, and operating system are not revealed to 
anyone else. If you are logging out after a remote login, the name of the node to 
which you return (the local node) is also revealed. If you access multiple accounts 
remotely over the network, the final sequence of logout commands reveals all 
the nodes and user names that are accessible to you on each node (excluding the 
name of the furthest node reached). To those who can recognize the operating 
system from the prompt or a logout message, these displays also reveal the 
operating system. 

At some sites, it might be important to leave nothing but the logout message on 
your screen, as follows: 

• If you are using a VT200 or later series terminal, you can clear the screen by 
pressing the Set-Up key and selecting the item from the resulting menu that 
corresponds to Clear Display. 

• If you are using a VT100 series terminal, press the Set-Up key. Then press 
the key marked for reset (the 0 key) followed by the Return key. 
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Alternately, to preserve temporary parameters, press the Set-U p key and then 
press the key marked 80/132 columns (the 9 key) twice. 

After the screen clears, the cursor is positioned at the top of the screen, next to 
the DCL prompt. Enter the DCL command LOGOUT at the prompt. The only 
information remaining after you log out is your logout command and the logout 
completion message. For example: 

$ LOGOUT 

RD0GW00D logged out at ll-DEC-1994 19:39:01.43 

2.11.2.2 Disposing of Hardcopy Output 

After you log out from a hardcopy terminal, remove, file, or dispose of all hardcopy 
output that might reveal sensitive information. Your security administrator 
should provide direction on preferred procedures. Many sites use paper shredders 
or locked receptacles for this purpose. Handle output that you plan to save just 
as carefully. 

You should also dispose of hardcopy output if the system fails before you log out. 
In addition, if you will not be present when the system is initialized, turn your 
terminal off. 

2.11.2.3 Breaking the Connection to a Dialup Line 

Your security administrator might ask you to break the connection to a dialup 
line when you log out. If you anticipate no further immediate use of the line, use 
the LOGOUT command with the /HANGUP qualifier. The /HANGUP qualifier 
directs the system to automatically break the connection to the dialup line after 
you log out. 


Note 

The effectiveness of the /HAN GUP qualifier depends on how your system 
manager configures your modem line and how the line connects to the 
computer. It does not work on lines connected to a terminal server. 


Breaking the connection to a dialup line prevents others from taking advantage 
of an open access line. To access the line, someone must know the access number 
and must personally redial. Breaking the connection is especially important if the 
dialup line you use is in a public area or where someone might use the terminal 
after you. 

This practice also saves resources by reducing the required number of dialup 
lines. 
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The DIGITAL Command Language: Interacting 

with the System 


This chapter describes how to use the DIGITAL Command Language. The 
DIGITAL Command Language (DCL) is a set of English-like instructions that tell 
the operating system to perform specific operations. 

DCL commands let you do the following: 

• Get information about the system. 

• Work with files. 

• Work with disks, magnetic tapes, and other devices. 

• Modify your work environment. 

• Develop and execute programs. 

• Provide security and ensure that resources are used efficiently. 

3.1 Using DCL Commands 

To enter a DCL command, type the command at the DCL prompt ( $ ) and press 
Return. DCL is not case sensitive; you can enter commands in either uppercase 
or lowercase letters. For example, to use the DCL command SHOW TIME, enter 
the foil owing command: 

$ SHOW TIME [R5IU7E1 

The system responds by displaying the current date and time and returns the 
DCL prompt to indicate it is ready to accept another command: 

ll-DEC-1994 15:41:43 

$ 

Table 3-1 lists the DCL commands you use to perform a few common computing 
tasks. Th eOpenVMS DCL Dictionary describes DCL commands in alphabetical 
order. 
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Table 3-1 Commonly Used DCL Commands 

Command Task 


COPY 

CREATE 

DELETE 

DIRECTORY 

EDIT 

LOGOUT 

PRINT 

RENAME 

SET 

SHOW 

TYPE 


Makes a copy of a specified file 
Creates files or directories 

Erases a specified file and removes it from a directory 
Displays the contents of a directory (list of files) 

Views and changes the contents of a text file 
Ends your session 

Sends a specified file to a printer for printing 
Changes the name or the location of a specified file 
Controls how you see the system on the screen 
Displays the status of the system 
Displays the contents of a specified file on the screen 


I n addition to these DCL commands, you can perform tasks by using specific key 
sequences. A key sequence is a shortcut or a way to get the system's attention 
while it is processing another command. 

To enter a key sequence, hold down the Ctrl key while you press and release a 
second key. 

Table 3-2 describes a few key sequences. (Additional key sequences are listed in 
Section 3.8.) 


Table 3-2 Commonly Used Ctrl Key Sequences 


Key Sequence 

Function 

Ctrl/C 

During command entry, cancels command processing. Ctrl/C displays 
on your screen as Cancel. 

Ctrl A' 

Interrupts command processing. Ctrl/Y displays on your screen as 

1 nterrupt. 

Ctrl/T 

Displays information about the current process, unless the system 
is temporarily unresponsive or is set to NOBROADCAST. For more 
information on using Ctrl/T, see Section 2.9. 


3.2 Constructing a DCL Command 

Like a spoken language, DCL is made up of words (vocabulary) and word order 
(syntax). The following sections describe these two elements and explain how to 
construct a valid DCL command. 

3.2.1 Vocabulary of a DCL Command 

Figure 3-1 shows the general format and parts of a DCL command line: 
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Figure 3-1 Parts of a DCL Command Line 


$ PRINT/COPIES = 5 


t 

DCL 

Prompt 


Qualifier that 
modifies the 
command 


GROCERY.LIS 

i 


Return 


Parameter 
(In this case, the 
parameter is a file 
specification) 


Value that 
modifies the 
qualifier 


DCL Command 


ZK-0950A-GE 

The following list describes the parts of a DCL command line from Figure 3-1: 

• DCL prompt 

The dollar sign ($) is the default DCL prompt. When you work interactively 
with DCL, DCL displays the prompt when it is ready to accept a command. 
When you write a command procedure, you must type the dollar sign at the 
beginning of each line. 

• DCL command 

A DCL command specifies the name of the command. The command can be a 
built-in command, a command that invokes a program, or a foreign command. 
I n this example, the DCL command is PRI NT. 

• Qualifier 

A qualifier modifies the action taken by the command. Some qualifiers modify 
the entire command, while others can modify specific command parameters. 
Some qualifiers can accept values. The DCL command descriptions in the 
OpenVMS DCL Dictionary indicate whether a specific qualifier can accept a 
value and what kind of value is acceptable. 

Qualifiers are always preceded by a slash (/). In this example, the qualifier is 
/COPIES. 

• Value 

A value modifies a qualifier and is often preceded by an equal sign (=). A 
value can be a file specification, a character string, a number, or a DCL 
keyword. A keyword is a word reserved for use in certain specified syntax 
formats. 

I n this example, the value is 5 (for 5 copies). 

• Parameter 

A parameter specifies what the command acts upon. You must position 
parameters in a specified order within the command. The DCL command 
descriptions in th e OpenVMS DCL Dictionary describe what parameter values 
are allowed for each command and where they must be placed. Examples of 
parameter values include file specifications, queue names, and logical names. 
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• Return key 

The Return key ends the DCL command line and signals to the system that 
the command is ready for processing. 

The following items (not shown in Figure 3-1) may also be used in a DCL 
command line: 

• Label 

A label identifies a line in a command procedure. Use labels only within 
command procedures, which are described in Chapter 15. 

• Keyword 

A keyword is a word defined for use in certain specified syntax formats. You 
must use keywords exactly as listed in the description of the particular DCL 
command you want to specify. For example, system, owner, group, and world 
are DCL keywords for the /PROTECTION qualifier of the SET SECURITY 
command. (A DCL keyword can also have a value.) 

• Wildcard character 

Wildcard characters are the asterisk (*), percent sign (%), ellipsis ( ... ) and 
hyphen (-). They can be used within, or in place of, a file name, file type 
directory name, or version number in a file specification to indicate all for 
the given field. For information about using wildcard characters with files 
and directories, see Chapter 4 and Chapter 5. For information about using 
wildcard characters with a particular DCL command, see the OpenVMS DCL 
Dictionary. 

3.2.2 Putting the Parts in Order: Syntax 

J ust as a spoken language depends on the order of words to create meaning, DCL 
requires that you put the correct elements of the command line in a specific word 
order. This word order, or syntax, is shown in a syntax diagram. 

The following syntax diagrams show the structure of typical DCL commands: 

command/qualifier=value=keyword 

command parameter/qualifier 

3.3 Entering a DCL Command 

When you enter a DCL command, some parameters are required; they must be 
entered on the command line. If you do not enter them, the system prompts you 
to supply the missing information. 

In the following example, the TYPE command requires a file specification. 
Because a file specification is a required parameter, if you do not enter one, the 
system requests it. A line beginning with an underscore (_) means that the 
system is waiting for your response. 

$ TYPE 

_File: WATER.TXT 

When you are prompted for an optional parameter, press Return to omit it. At 
any prompt, after you enter the required parameter, you can enter one or more of 
the remaining parameters and any additional qualifiers. 

If you press Ctrl/Z after a command prompt, DCL ignores the command and 
redisplays the DCL prompt. 
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Some items, called defaults, need not be specified on the command line. When 
DCL does something by default, it assigns a command certain values or to takes 
certain actions without your having to specify them explicitly. I n general, the 
values and actions are those considered typical or expected by users. 

For example, if you do not specify the number of copies as a qualifier for the 
PRI NT command, DCL uses the default value 1. Unless you specify otherwise, 
DCL uses the default. You can override this default and print multiple copies of a 
file by including the /COPI ES qualifier on the PRI NT command line: 

$ PRINT/C0PIES=4 MYFILE.TXT 

DCL supplies default values in several areas, including command parameters and 
qualifiers. Parameter defaults are described in the following section. Qualifier 
defaults are described in Section 3.3.4. 

3.3.1 Rules for Entering a DCL Command 

Use the following rules to enter a DCL command: 

• Use any combination of uppercase and lowercase letters. The DCL interpreter 
translates lowercase letters to uppercase. Uppercase and lowercase 
characters in parameter and qualifier values are equivalent unless enclosed 
in quotation marks (" "). 

• Separate the command name from the first parameter with at least one blank 
space or a tab. 

• Separate each additional parameter from the previous parameter or qualifier 
with at least one blank space or a tab. 

• Begin each qualifier with a slash (/). The slash serves as a separator and 
need not be preceded by blank spaces or tabs. 

• Include no more than 127 elements (parameters, qualifiers, and qualifier 
values) in each command line. 

Each element in a command must not exceed 255 characters. The entire 
command must not exceed 1024 characters after all symbols and lexical 
functions are converted to their values. You use symbols, described in 
Chapter 14, to pass information to the system in an abbreviated manner. 

A lexical function, described in Chapter 16, obtains information from the 
system, including information about system processes, batch and print 
queues, and user processes, and then substitutes the result of the operation 
for itself. 

• If a parameter or qualifier value includes a blank space or a tab, enclose the 
parameter or qualifier value in quotation marks. 

You can abbreviate a command as long as the abbreviated name remains unique 
among the defined commands on a system. DCL looks only at the first four 
characters for uniqueness. For example, the following commands are equal: 

$ PRIN/C0PI=2 F0RMAL_ART.TXT 
$ PRINT/C0PIES=2 F0RMAL_ART.TXT 

For greater clarity and to ensure that your command procedures are upwardly 
compatible, do not abbreviate commands in command procedures. 

Additional rules govern the format of commands when they are used in command 
procedures. See Chapter 15 for more information about using commands in 
command procedures. 


3-5 


The DIGITAL Command Language: Interacting with the System 
3.3 Entering a DCL Command 

3.3.2 Entering a Command That Is Longer Than One Line 

If you enter a command longer than one line, you can continue the command 
onto the next line. Continue a command line onto the next line by following this 
procedure: 

1. End the command line with a hyphen (-) and press Return. 

The system displays an underscore (_) followed by the DCL prompt ($). 

2. Enter the rest of the command line after this prompt. 

A line beginning with an underscore means that the system is waiting for 
your response, as shown in the following example: 

$ COPY/LOG FORMAT. TXT, FIGURE. TXT, ARTWORK. TXT - 
_$ SAVE . TXT 

Note that you must include the appropriate spaces between command names, 
parameters, and so on. Pressing Return after the hyphen does not add a space. 

You can also enter a long command line without specifying a hyphen; the system 
automatically wraps text to the next line. However, separating portions of the 
command lines with hyphens makes the command line easier to read. 

There is no restriction to the number of continued lines you can use to enter a 
command, as long as you do not exceed the 1024-character limit. 

3.3.3 Entering Parameters 

DCL supplies default values for some command parameters. The parameters 
accepted by a command as well as the specific command parameter defaults 
supplied by DCL are described in each command description in the OpenVMS 
DCL Dictionary. 

File specifications are the most common type of parameter. DCL commands can 
accept input file specifications (files that are acted upon by a command) and 
output file specifications (files that are created by a command). 

The following rules apply when specifying parameters in a command line: 

• Square brackets ([]) in command descriptions indicate optional items. 

For example, you do not have to enter a file specification in the following 
command: 

DIRECTORY [file-spec] 

• In a command description, anything not enclosed in square brackets is 
required. For example, you must enter a device name in the following 
command: 

SHOW PRINTER device-name 

• I n general, precede an output file parameter with an input file parameter. For 
example, to copy the input file, LISTS.TXT, to the output file, FORMAT.TXT, 
enter the following command: 

$ COPY LISTS.TXT FORMAT.TXT 

• A parameter can be one item or a series of items. If you enter a series of 
items, separate the items with commas (, ) or plus signs ( +). Any number 
of spaces or tab characters can precede or follow a comma or a plus sign. 
Note that some commands regard the plus sign as a concatenator, not as a 
separator. The parameter section of each DCL command description in the 
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OpenVMS DCL Dictionary describes how each command interprets commas 
and plus signs. 

The following command syntax line shows that you can optionally enter a list 
of file specifications as the parameter: 

DELETE file-spec[,...] 

The following example shows how to specify a list of parameters. Here, 
three files are copied to a fourth file. The three file specifications, 
PLUTO.TXT, SATURN.TXT, and EARTH .TXT, constitute the first parameter. 
PLANETS.TXT is the second parameter. 

$ COPY PLUTO.TXT, SATURN. TXT, EARTH. TXT PLANETS.TXT 

Note that there are no spaces between the PLUTO.TXT, SATURN.TXT, and 
EARTH.TXT file specifications. 

3.3.4 Entering Qualifiers 

The qualifiers accepted by a command are described in the command descriptions 
in the OpenVMS DCL Dictionary. The DCL command description also indicates 
whether a qualifier accepts a value and what kind of value is required. 

You can abbreviate any qualifier name as long as the abbreviated name remains 
unique among all qualifier names for the same command. However, to ensure 
that your command procedures are upwardly compatible, do not abbreviate 
commands and qualifiers in command procedures. 

Commands have default qualifiers; you do not have to specify a qualifier unless 
it is different from the command default. The following sections describe types of 
qualifiers and qualifier defaults. The OpenVMS DCL Dictionary contains default 
information for specific commands. 

3.3.4.1 Types of Qualifiers 

The three types of qualifiers are as follows: 

• Command qualifiers 

A command qualifier modifies a command and can appear anywhere in the 
command line. However, it is a good practice to place the qualifier after the 
command name. If you are specifying multiple qualifiers, you should place a 
command qualifier with other command qualifiers that follow the command 
name. 

In the following example, /QUEUE is a command qualifier. The files 
SATURN.TXT and EARTH .TXT are queued to the print queue LN03_PRI NT. 

$ PRINT/QUEUE=LN03_PRINT SATURN . TXT, EARTH . TXT 

• Positional qualifiers 

A positional qualifier can modify commands or parameters and has different 
meanings depending on where you place it in the command string. If you 
place a positional qualifier after the command but before the first parameter, 
it affects the entire command string. If you place a positional qualifier after a 
parameter, it affects only that parameter. 

I n the following example, the first PRI NT command requests two copies of the 
files SPRI NG. SUM and FALL. SUM. The second PRINT command requests 
two copies of the file SPRI NG. SUM but only one copy of FALL.SUM . 
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$ PRINT/COPIES=2 SPRING. SUM, FALL. SUM 
S PRINT SPRING. SUM/COP IES=2, FALL. SUM 

• Parameter qualifiers 

A parameter qualifier can be used only with certain types of parameters, such 
as input files and output files. 

For example, the BACKUP command accepts several parameter qualifiers 
that apply only to input and output file specifications. I n the following 
example, the /CREATED and /BEFORE qualifiers, which can be specified 
only with input files, select specific input files for the backup operation. The 
asterisk (*) is a wildcard character that replaces the file name. BACKUP 
selects all files with the .TXT file type that were created before December 11, 
1993. 

$ BACKUP * . TXT/CREATED/BEFORE=ll-DEC-1994 NEWFILE.TXT 

If you use two or more contradictory qualifiers on a command line, the right- 
most qualifier overrides the others. For example, the following PRI NT command 
accepts only the/COPI ES=2 and the /NOBURST qualifiers: 

$ PRINT MYFILE/COPIES=3/BURST/COPIES=2/NOBURST EARTH.TXT 

Some commands contain conflicting qualifiers that cannot be specified in the 
same command line. If you use incompatible qualifiers, the command interpreter 
displays an error message. The command descriptions in the OpenVMS DCL 
Dictionary indicate which qualifiers cannot be used together. 

3.3.4.2 Values Accepted by Qualifiers 

Qualifiers can accept keywords, file specifications, character strings, and numeric 
values. When you enter a value for a qualifier, separate the qualifier and the 
value with either an equal sign ( =) or a colon ( : ). For example: 

$ PRINT/C0PIES=3 MYFILE.DAT 

$ PRINT/COPIES: 3 MYFILE.DAT 

Some qualifier keywords require additional information. I n these cases, separate 
the keyword from its value with a colon or an equal sign. For example: 

$ SET SECURITY/PROTECTION: GROUP :RW MYFILE.DAT 
$ SET SECURITY/PROTECTION=GROUP=RW MYFILE.DAT 

To specify multiple keywords that require values, enclose the list in parentheses 
and separate the keyword and value with either an equal sign ( =) or a colon ( : ). 
For example: 

$ SET SECURITY/PROTECTION= (0WNER=RWD, GR0UP=RW) myfile.dat 
$ SET SECURITY/PROTECTION= (OWNER: RWD, GROUP : RW) myfile.dat 

3.4 Entering Dates and Times as Values 

Certain commands and qualifiers (such as the PRINT/AFTER command) accept 
date and time values. You can specify these values in one of the following 
formats: 

• Absolute time 

• Delta time 

• Combination time (combines absolute and delta time formats) 
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The DCL command descriptions in the OpenVMS DCL Dictionary indicate the 
time formats accepted by individual commands and qualifiers. 

3.4.1 Absolute Time 

Absolute time is a specific date or time of day. The format for an absolute time is 
as follows: 

[dd-mmm-yyyy][:hh:mm:ss.cc] 

The fields are as follows: 

dd Day of the month; an integer in the range 1 to 31 

mmm Month; JAN, FEB, MAR, APR, MAY, J UN,J UL, AUG, SEP, OCT, NOV, or DEC 

yyyy Year; an integer 

hh Hour; an integer in the range 0 to 23 

mm M inute; an integer in the range 0 to 59 

ss Second; an integer in the range 0 to 59 

cc Hundredths of a second; an integer in the range 0 to 99 

The following rules apply: 

• You can truncate the date or the time on the right. 

• If you specify both a date and a time, include a colon between them. 

• The date must contain at least one hyphen. 

• You can omit any of the fields within the date and time as long as you include 
the punctuation marks that separate the fields. 

• A truncated or omitted date field defaults to the corresponding fields for the 
current date. 

• A truncated or omitted time field defaults to zero. 

• If you specify a past time in a command that expects the current or a future 
time, the current time is used. 

You can also specify an absolute time as one of the following keywords: 

TODAY The current day, month, and year at 00:00:00.0 o'clock 

TOMORROW 00:00:00.00 o'clock tomorrow 

YESTERDAY 00:00:00.00 o'clock yesterday 

The following table shows some examples of absolute time specifications: 


Time Specification 

Result 

11-DEC-1994:13 

11-DEC 

15:30 

19- 

19— :30 

1 p.m. on December 11, 1994 

Midnight at the beginning of December 11 this year 

3:30 p.m. today 

Midnight on the 19th day of the current year and month 

12:30 a.m. on the 19th of this month 
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3.4.2 Delta Time 

Delta time is an offset (a time interval) from the current date and time to a time 
in the future. The general format of a delta time is as follows: 

"+[dddd-][hh:mm:ss.cc]" 

The fields are as follows: 

dddd Number of days; an integer in the range 0 to 9999 

hh Number of hours; an integer in the range 0 to 23 

mm Number of minutes; an integer in the range 0 to 59 

ss Number of seconds; an integer in the range 0 to 59 

cc Number of hundredths of seconds; an integer in the range 0 to 99 

The following rules apply: 

• You can truncate a delta time on the right. 

• If you specify the number of days, include a hyphen. 

• You can omit fields within the time as long as you include the punctuation 
that separates the fields. 

• If you omit the time field, the default is zero. 

The following table shows some examples of delta time specifications: 


Time Specification 

Result 

"+ 3 -" 

3 days from now (72 hours) 

"+ 3 " 

3 hours from now 

"+:30" 

30 minutes from now 

"+3-:30" 

3 days and 30 minutes from now 

"4-15:30" 

15 hours and 30 minutes from now 


3.4.3 Combination Time 

To combine absolute and delta times, specify an absolute time plus or minus a 

delta time. Use one of the following formats: 

"[absolute time][+delta time]" 

[absolute time][-delta time] 

The variable fields and default fields for absolute and delta time values are the 

same as those descri bed in the preceding sections. In addition, do the following: 

• Precede the delta time value by a plus or minus sign. (Note that the minus 
sign is the same keyboard key as the hyphen.) 

• Enclose the entire time specification in quotation marks if a plus or minus 
sign precedes the delta time value. 

• Omit the absolute time value if you want to offset the delta time from the 
current date and time. 

• Specify date and time information as completely as possible. 
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The following table shows some examples of combination time specifications: 


Time Specification 

Result 

"+5" 

5 hours from now. 

"-1" 

Current time minus 1 hour. The minus sign (-) indicates a 
negative offset. (The 1 is interpreted as an hour, not a day, 
because it is not followed by a hyphen.) 

"+:5" 

5 minutes from now. 

"_:5" 

Current time minus 5 minutes. 

"-1-00" 

Current time minus 1 day. The minus sign (-) indicates a 
negative offset. The hyphen ( - ) separates the day from the time 
field. 

"31-DEC:+:5" 

12:05 a.m. on December 31 of the current year. The absolute time 
specification (before the colon) defaults to midnight on December 
31 of the current year. The plus sign ( +) indicates a positive 
offset. 

31-DEC:-00:10 

11:50 p.m. on December 30 of the current year. The absolute time 
specification (before the colon) defaults to midnight on December 
31 of the current year. The minus sign (-) after DEC: indicates 
a negative offset. 


If a qualifier is described as a value that can be expressed as an absolute time, 
a delta time, or a combination of the two, you must specify a delta time as if it 
were part of a combination time. For example, to specify a delta time value of 
five minutes from the current time, use "+:5" (not "0-0:5"). 


3.5 Recalling Commands 

At the DCL prompt, you can recall previously typed command lines to avoid 
retyping long command lines. Once a command is displayed, you can reexecute or 
edit it. 



AXP 


On OpenVMS VAX systems, the recall buffer holds up to 20 previously entered 
commands. ♦ 

On OpenVMS AXP systems, the recall buffer holds up to 254 previously entered 
commands.* 

You can display your previously entered commands by using one of the following 
methods: 


• Pressing Ctrl/B 

• Using up arrow and down arrow keys 

• Entering the RECALL command 

Pressing Ctrl/B once recalls the previous command line. Pressing Ctrl/B again 
recalls the line before the previous line and so on to the last saved command line. 

Pressing the up arrow and down arrow keys recalls the previous and successive 
command, respectively. Press the arrow keys repeatedly to move through the 
commands. 

To examine previously typed command lines, type RECALL/ALL. Following is a 
sample display generated by typing RECALL/ALL: 
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$ RECALL/ALL 

1 SET DEFAULT DISK2 : [MARSHALL] 

2 EDIT ACCOUNTS.COM 

3 PURGE ACCOUNTS.COM 

4 DIRECTORY/FULL ACCOUNTS.COM 

5 COPY ACCOUNTS.COM [.ACCOUNTS]* 

6 SET DEFAULT [.ACCOUNTS] 

After reviewing the available commands, you can recall a particular command 
line by typing RECALL and the number of the desired command. The following 
example shows how to recall the fourth command line: 

$ RECALL 4 

After you press Return, the system displays the fourth command in the list at the 
DCL prompt. (The RECALL command itself is not placed in the buffer.) 

You can also follow RECALL with the first characters of the command line you 
want to display. RECALL scans the previous command lines (beginning with 
the most recent one) and returns the first command line that begins with the 
characters you typed. For example, to recall a previously entered command, 

EDIT ACCOUNTS.COM, enter the following command: 

$ RECALL E 

After you press Return, the system displays the following command line: 

$ EDIT ACCOUNTS.COM 


Note 

If you are running a utility or an application program that uses OpenVMS 
screen management software, you can use Ctrl/B and the up arrow and 
down arrow keys to perform command recall; however, line editing must 
be enabled. Some utilities that have this feature are Mail, OpenVMS 
Debugger, Show Cluster, the System Dump Analyzer (SDA), and the EVE 
editor. 


To erase the contents of the recall buffer, enter the RECALL command with the 
ERASE qualifier. For example: 

$ RECALL/ERASE 

For security reasons, it is good practice to erase the contents of the recall buffer 
after you have entered commands that include passwords. 

3.6 Editing the DCL Command Line 

At the DCL command level, you can use many individual keys and key sequences 
to change what you type. Although different types of terminals have different 
operating characteristics, most have standard function keys, and keys that can be 
used with line editors. 
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3.6.1 Setting Up Your Terminal for Line Editing 

To see whether line editing is enabled on your terminal, enter the SHOW 
TERMI NAL command. The current status of line editing is displayed in the first 
column under Terminal Characteristics. 


$ SHOW TERMINAL 


Parity: None 


Terminal: _VTA130: Device_Type: VT200_Series Owner: ROHBA 

LAT Server/Port: L121/Port_3 
Physical terminal: _LTA130: 

Input: 9600 LFfill: 0 Width: 80 

Output: 9600 CRfill: 0 Page: 24 

Terminal Characteristics: 

Interactive 
No Hostsync 
Wrap 

Broadcast 
No Modem 
No Brdcstmbx 
No Line Editing 
No Secure server 


Echo 

TTsync 

Scope 

No Readsync 
No Local_echo 
No DMA 

Insert editing 
Disconnect 


No SIXEL Graphics 

ANSI_CRT 

No Edit mode 


No Soft Characters 
No Regis 
DEC CRT 


Type_ahead 
Lowercase 
No Remote 
No Form 
No Autobaud 
No Altypeahd 
No Fallback 
No Pasthru 
No Printer Port 
No Block_mode 
No DEC CRT2 


No Escape 
Tab 

No Eightbit 
Fulldup 
Hangup 
Set_speed 
No Dialup 
No Syspassword 
Numeric Keypad 
Advanced_video 


I n this example, line editing is not enabled. To enable line editing, enter the SET 
TERMI NAL/L IN E_EDIT command: 

$ SET TERMINAL/LINE_EDIT 

You can also use the SET TERMI NAL command to alter the way in which your 
terminal edits a DCL command line: 


• SET TERMINAL/INSERT and SET TERMINAL/OVERSTRIKE 

You can edit a command line in either insert or overstrike mode. In insert 
mode, the character you type is inserted to the left of the cursor. I n 
overstrike mode, the character you type overwrites the character indicated by 
the cursor. 

To change editing modes for a single command line, press Ctrl/A (Ctrl/A acts 
as a toggle). 

• SET TERMINAL/WRAP 

When you enter more characters than will fit on one line of the terminal 
screen, the text wraps to the next line. 

You can edit only the line where your cursor appears. When text wraps, you 
cannot use the up arrow key to move the cursor up to edit the previous line. 
To move the cursor up to the previous line, use the Delete key and delete all 
the characters in the current line. 

By default, changes made with the SET TE RM I NAL command apply only to 
the current session. To set the terminal each time you log in, you can include 
SET TERM I NAL commands in your LOGIN.COM file. For more information on 
the SET TERM I NAL command, see the OpenVMS DCL Dictionary. For more 
information on LOGIN.COM, see Chapter 15. 
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3.6.2 Deleting Portions of the Command Line 

The Delete key on your keyboard is marked with either the word Rubout, the 
word Delete, or an X in a left-pointing arrow, depending on the type of terminal 
you are using. The Delete key back spaces over the most recently entered 
character and deletes it. On a hardcopy terminal, the deleted letters are 
displayed between backslash characters so you can see what is being deleted. On 
a video display terminal, pressing the Delete key erases the character from the 
screen and moves the cursor backwards. 

In contrast, the Backspace key (or the left arrow key) back spaces over characters 
but does not delete them. 

If line editing is enabled, you can use Ctrl/U to delete characters from the 
beginning of the line to the current cursor position. If line editing is not enabled, 
you can use Ctrl/U to cancel an entire line. The system ignores the line and 
redisplays the DCL prompt. 

3.7 Defining Terminal Keys 

Using key definitions, you can customize your keyboard so that you can enter 
DCL commands with fewer keystrokes. A key definition is a string of characters 
that you assign to a particular terminal key. When a key is defined, you can press 
it instead of typing the string of characters. A key definition usually contains 
all or part of a command line. When you press a defined key, the system either 
displays the command on your terminal or executes the command, depending on 
if the command was defined using the /TERMI NATE qualifier. 

Some definable keys are automatically enabled for definition (for example, keys 
PF1 to PF4 and keys F17 to F20 on LK201 keyboards). However, before you can 
define other keys, including KPO (keypad 0) to KP9 and the keypad keys period, 
comma, minus, and Enter, you must enable them for definition by entering 
either the SET TERMI NAL/APPLICATION_KEYPAD or the SET TERMINAL 
/NONUMERIC command. 

For a complete list of definable keys and for more information on how to create 
key definitions, see the description of the DCL command DEFI N E/KEY in the 
OpenVMS DCL Dictionary. 

3.8 Summary of Key Sequences 

Table 3-3 lists and describes the key sequences that let you enter and edit DCL 
commands. 


Table 3-3 Keys That Execute Terminal Functions 


Key 

Function 

Keys That Enter DCL Commands 

Ctrl/Zand F10 1 

Signals the end of the file for data entered from the terminal. Ctrl/Z 
displays as Exit. 

Return 

Sends the current line to the system for processing. On some 
terminals, the Return key is labeled CR. 


1 Thi s key is available only on an LK201 keyboard. 


(continued on next page) 
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Table 3-3 (Cont.) Keys That Execute Terminal Functions 


Key 

Function 

Keys That Enter DCL Commands 


If you are not already logged in, Return initiates a login sequence. 

Keys That Interrupt DCL Commands 

Ctrl/C and F6 1 

During command entry, cancels command processing. Ctrl/C 
displays as Cancel. 

Ctrl/T 

Momentarily interrupts terminal output to display a line of 
statistical information about the current process. This display 
includes your node and user name, the time, the name of the image 
you are running, and information about system resources used 
during your current terminal session. 

You can also use Ctrl/T to determine whether the system is 
operating. Ctrl/T does not return information if the system 
is temporarily unresponsive or if your terminal is set to 
NOBROADCAST. To use Ctrl/T, you must first enter the SET 
CONTROL=T command (in the system login command procedure, in 
your personal login command procedure, or interactively). 

Ctrl A' 

Interrupts command processing. Ctrl/Y displays as Interrupt. You 
can disable Ctrl/Y with the command SET NOCONTROL=Y. 

Under most conditions, Ctrl/Y returns you to the DCL prompt. 

The program running is still active. You can enter any built- 
in command then continue the program with the CONTINUE 
command. (Press Ctrl/W to refresh the screen after you enter the 
CONTINUE command.) 

Keys That Recall Commands 

Ctrl/B or up arrow 

Recalls up to 20 previously entered commands. 

Down arrow 

Displays the next line in the recall buffer. 

Keys That Control Cursor Position 

O, Delete 

Deletes the last character entered at the terminal. On some 
terminals, the Delete key is labeled RUBOUT. The Delete key 
also works when line editing is disabled. 

Ctrl/A and F14 1 

Switches between overstrike and insert mode. The default mode (as 
set with the SET TERMINAL/LINE_EDITING command) is reset at 
the beginning of each line. 

Ctrl/D and left arrow 

Moves the cursor one character to the left. 

Ctrl/E 

M oves the cursor to the end of the 1 i ne. 

Ctrl/F and right arrow 

Moves the cursor one character to the right. 

Ctrl/H, Backspace, and F12 1 

Moves the cursor to the beginning of the line. 

Ctrl/I and Tab 

Moves the cursor to the next tab stop on the terminal. The system 
provides tab stops at every eighth character position on a line. Tab 
settings are hardware terminal characteristics that, in general, you 
can modify. The Tab key also works when line editing is disabled. 


^This key is available only on an LK201 keyboard. 


(continued on next page) 
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Table 3-3 (Cont.) Keys That Execute Terminal Functions 

Key Function 


Keys That Control Cursor Position 

Ctrl/J , Linefeed, and F13 1 Deletes the word to the left of the cursor. 

Ctrl/K Advances the current line to the next vertical tab stop. 

Ctrl/L Causes the cursor to go to the beginning of the next page. This use 

of Ctrl/L is ignored when line editing is enabled. 

Ctrl/R Repeats the current command line and leaves the cursor positioned 

where it was when you pressed Ctrl/R. 

Ctrl/U Deletes all text in the current input line that is to the left of the 

cursor. 

Ctrl/V Turns off some of the line editing function keys. For example, if you 

press Ctrl/V followed by Ctrl/D, a Ctrl/D is generated instead of the 
cursor moving left one character. Ctrl/D is a line terminator at DCL 
level. 

When combined with Ctrl/V, characters that are not line terminators 
have no effect. Examples are Ctrl/H and Ctrl/J . However, certain 
control keys, such as Ctrl/U, retain their line editing functions. 

Ctrl/X Cancels the current line and deletes data in the type-ahead buffer. 

F7, F8, F9, Fll Reserved by Digital. 


Keys That Control Screen Display 

Ctrl/O Alternately suspends and continues display of output to the 

terminal. Ctrl/O displays as Output off and Output on. 

Ctrl/S Suspends terminal output until Ctrl/Q is pressed. 

Ctrl/Q Resumes terminal output suspended by Ctrl/S. 

Hold Screen 1 and No Scroll 2 Suspends terminal output until the key is pressed again. 

^-Thi s key is available only on an LK201 keyboard. 

2 This key is available only on a VT100 keyboard. 
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Files: Storing Information 


A file is a unit that the OpenVMS operating system uses to store human-readable 
and machine-readable data. This chapter describes how to create and manipulate 
files locally, and if you have sufficient privileges, over a DECnet for OpenVMS 
network. 

For more information on the DCL commands described in this chapter, refer to 
DCL Help (described in Section 2.10) or see the OpenVMS DCL Dictionary. 

4.1 Understanding File Names and File Specifications 

When you create or name a file, you must specify certain information so that 
the system can locate and identify the file. You do not have to include all the 
elements of a complete file specification (see Section 4.1.1). However, you must 
include a file name or file type to identify it to both the system and you. For 
example, PAYROLL_MEMO.TXT is a valid file specification. PAYROLL_MEMO is 
the file name, and .TXT is the file type. 

4.1.1 Providing a Complete File Specification 

To override system defaults or to perform file operations over a network, you 
must provide a complete file specification. A complete file specification has the 
following format: 

node::device:[directory]filename.filetype;version 
The elements are as follows: 


Node 

A network node name; applicable only to systems that support 
DECnet for OpenVMS. Does not apply to files stored on magnetic 
tape. 

Device 

The name of the physical device on which the file is stored or is to be 
written. For information on accessing files stored on physical devices, 
see Section 12.5. 

Directory 

The name of the directory under which the file is cataloged. Square 
brackets ([ ]) or angle brackets (o) can be used to delimit directory 
names. Does not apply to files stored on magnetic tape. 

Filename 

The name of the file. It can have up to 39 alphanumeric characters, 
including the hyphen and the underscore. 

Filetype 

Identification of the structure or the type of data in the file. The 
file type can have up to 39 alphanumeric characters, including the 
hyphen and the underscore. 

Version 

The version number of the file. Versions are identified by a decimal 
number, which is incremented by 1 each time a new version of the 
file is created. The system automatically assigns a version number 
unless you specify one. 
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Use the following rules to specify the elements of a file specification: 

• Give the file a name that is meaningful to you. The file name can be up to 
39 characters chosen from the letters A to Z (uppercase or lowercase), the 
numbers 0 to 9, underscores (_), hyphens (-), and dollar signs ( $). 

• Do not use a hyphen as the first or last character in the file name. While it is 
possible under some conditions to successfully create a file with the hyphen 
as the first character in the file name, special handling is required to access 
this file. 

• I nclude 0 to 39 characters in a file type. 

• Precede a file type by a period. 

• Precede version numbers with a semicolon or a period. (When the system 
displays file specifications, it displays a semicolon in front of the file version 
number.) 

• Do not use a directory field to refer to files on magnetic tape (directories apply 
only to files on disks). 

• I nclude a node name only if your system is part of a network. 

The fields for file name, type, and version apply to all files on mass storage 
devices (such as disks and magnetic tapes). 

With certain commands, if you omit the file type, the system applies a default 
value. Table 4-1 lists some of the more common default file types used by DCL 
commands. Table 4-2 lists the default file types for some high-level language 
source programs. 


Table 4-1 Default File Types for DCL Commands 


File Type 

Contents 

.CLD 

Command description file 

.COM 

Command procedure file 

.DAT 

Data file 

.DIF 

Output file created by the Dl FFERENCES command 

.DIR 

Directory file 

.DIS 

Distribution list file for the Mail utility 

.EDT 

Startup command file for the EDT editor 

.EXE 

Executable program image file created by the linker 

.HLB 

Help text library file 

.HLP 

1 nput source file for help libraries 

.INI 

1 nitialization file 

.J OU 

J ournal file created by the E DT editor 

.LIS 

Listing file created by a language compiler or assembler: default 
input file for the PRI NT and TYPE commands 

.LOG 

Batch job output file 

.MAI 

Mail message file 


(continued on next page) 
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Table 4-1 (Cont.) Default File Types for DCL Commands 


File Type 


Contents 

.MEM 


Output file created by DIGITAL Standard Runoff (DSR) 

.PS 


PostScript format file 

.REGIS 


Regis format file 

.RNO 


Input source file for DIGITAL Standard Runoff (DSR) 

.SIX 


Sixel graphic file 

.SYS 


System image file 

■TJ L 


J ournal file created by the DECTPU and ACL editors 

.TLB 


Text library file 

.TMP 


Temporary file 

.TPU 


Command file for the EVE editor 

,TPU$J OURNAL 

J ournal file created by the EVE editor 

.TXT 


1 nput file for text libraries or Mail utility output files 

Table 4-2 

Default File Types for Language Source Programs 

File Type 


Contents 

.ADA 


Input source file for the DEC Ada compiler 

.BAS 


Input source file for the BASIC compiler 

.B32 


Input source file for the VAX BLISS-32 compiler 

.C 


1 nput source file for the DEC C compiler 

.COB 


Input source file for the VAX COBOL compiler on OpenVMS 

VAX systems and the DEC COBOL compiler on OpenVMS AXP 
systems 

.FOR 


Input source file for DEC Fortran (DEC Fortran for OpenVMS 
VAX systems was formerly VAX Fortran) 

.M64 


Input source file for the MACRO-64 assembler for OpenVMS AXP 

.MAP 


Memory allocation map created by the Linker utility 

.MAR 


Input source file for the VAX MACRO assembler or the MACRO-32 
Compiler for OpenVMS AXP. 

.MLB 


Macro library for the MACRO assembler 

.MSG 


Source file that specifies the text of messages 

.OBJ 


Object file created by a language compiler or assembler 

.OLB 


Object module library 

.OPT 


Options file for input to the LINK command 

.PAS 


1 nput source file for the Pascal compiler 

.PLI 


Input source file for the PL/I compiler 

.STB 


Symbol table file created by the Linker utility 

.UPD 


Update file of changes for a VAX MACRO source program; also 
input totheSUMSLP utility 


I n addition to a file name and file type, every file has a version number. Version 
numbers are decimal numbers from 1 to 32,767 that differentiate versions of a 
file. When you create a file, the system assigns it a version number of 1. 
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You can have several versions of the same file. Unless you specify a version 
number, the system uses the highest existing version number of that file. If you 
specify a version number of 0, the system uses the highest existing version. When 
you modify a file with a command, application, or text editor (such as EVE) that 
creates a new version of the file, the file name remains the same, but the version 
number is incremented by one. 

Precede version numbers with a semicolon or a period. When the system displays 
file specifications, it displays a semicolon in front of the file version number. 

You can refer to versions of a file in a relative manner by specifying a zero or a 
negative version number. Specifying zero locates the latest (highest numbered) 
version of the file. Specifying -l locates the next-most-recent version, -2 the 
version before that, and so on. To locate the earliest (lowest numbered) version of 
a file, specify -0 as the version number. Note that you cannot create files with 
a version number higher than 32767. If you attempt to create a new file with a 
version number higher than 32767, you will receive an error message. 

The/VERSIONJJMIT qualifier for the CREATE/DI RECTORY, SET 
DIRECTORY, and SET FILE commands lets you control the number of versions 
of a file. If you exceed the version limit, the system automatically purges the 
lowest version file in excess of the limit. For example, if the version limit is 5 
and you create the sixth version of a file (ACCOUNTS. DAT;6), the system deletes 
the first version of the file (ACCOUNTS. DAT;1). To view the version limit on a 
file, enter the Dl RECTORY /FULL command. The version limit is listed the File 
attributes section. 

4.1.2 Specifying Network Node Names 

A node is an individual computing system that is part of a computer network. 

If your system is part of a network, the node that you access when you log in is 
your local node. Other nodes in the network are remote nodes. Use a node name 
when you want to specify a file on a remote node. 

A node specification has the following format: 

node["access-control-string"]:: 

Observe the following rules when entering a node name as part of a file 
specification: 

• Node names can contain 1 to 6 alphanumeric characters and must contain at 
least one alphabetic character. For example: 

AFTP1 

F20TR2 

MYNODE 

• A node name (with or without an access control string) must always be 
followed by a double colon ( :: ). 

• When you specify a node name, you can include a 0- to 42-character access 
control string. An access control string contains login information to be 
sent to the remote node. For more information on access control strings, see 
Section 4.1. 4.2. 

Note that the required double colon follows the access control string. 

• You can use a logical name in place of the node name. For information on 
logical node names, see Chapter 13. 
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4.1.3 Specifying Node Full Names (VAX only) 


On VAX systems, you can specify node full names. However, you must have 
DECnet/OSI software installed for full node names to be recognized. By default, 
OpenVMS VAX Version 6.1 includes DECnet for OpenVMS VAX software, which 
is subject to the rules listed in Section 4.1.2. 

Valid full node names can contain up to 255 characters and can include any 
characters except the following: 

• Spaces 



• Tabs 


• The characters: comma (,), quotation marks (" "), slash (/), exclamation 
point ( ! ), plus sign ( +), at sign ( @), apostrophe ( '), parentheses ( ( ) ), and 
double colons ( :: ) 

• A single colon ( : ) as the first or last character 

If a full node name is enclosed in quotation marks (" "), it can contain any 
characters except unmatched quotation marks. Note that if there are quotation 
marks within the node name, the quotation marks must be doubled, and the 
entire string, including the quotation marks, must also be enclosed in quotation 
marks. For example: 

"MARY: .UNIVERSITY. ""SCIENCE LAB""" 

Other examples of valid full node names are: 

MYNODE 

M ASSACH USETTS:.BUSI N ESS.Y OU RNODE 
A.B;C 

Although the OpenVMS software enforces few rules on the syntax of node names, 
the actual set of valid node names is constrained by the DECnet software running 
on your system. For further information on full names, refer to the DECnet/OSI 
documentation. ♦ 


4.1.4 Accessing Files on Remote Nodes 


When you access a file on a remote node, DECnet logs in at the remote node. To 
do this, the system needs login information for that node. You can supply the 
system with an access control string. If you omit the access control string, the 
login information sent to the remote node is determined as follows: 

• If a proxy login account exists for you on the remote node, then the system 
logs you in using that account. A proxy login account allows selected users to 
log in to a node. 

• If a proxy login account does not exist, the system uses the default DECnet 
account for that node as specified by the local system manager. 

If you include an access control string, the system uses it to log you in to the 
remote node. The remainder of the file specification is passed to the remote node 
and is interpreted there. 

If you specify a local node as part of a file specification, the system logs you in 
over the network to perform the file operation, even though the file exists on your 
local node. For information about additional ways to access remote systems, see 
the OpenVMS System Manager's Manual. 
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Note 

Throughout the remainder of this chapter, examples that specify a node 
name do not always include an access control string. This is because 
proxy accounts enable users to perform operations on the remote systems 
in these examples. 


4.1 .4.1 Using Network File Specifications 

There are three formats for network file specifications. I n each format, the node 
specification can include an access control string. 

• Conventional format for files: 
node::device:[directory]filename.type;version 

• Format used to provide a foreign file specification: 
node::"foreign-file-spec-string" 

A foreign file specification is a file that does not conform to OpenVMS 
syntax. For example: 

$ COPY BOSTON: : "TEST7.DAT" * 

The preceding file name contains a question mark ( ?), which is not recognized 
as a valid file name character. Therefore, the file name must be enclosed in 
quotation marks (" "). It must also be in a format that is recognized by the 
operating system of the remote node you are accessing. 

Note 

There are some restrictions when you copy files to or from an ULTRIX 
system. For more information, see the OpenVMS Record Management 
U ti I i ti es R tference M an ual . 


• Format used to indicate a task specification string: 
node : : “task-spec-stri ng ” 

A task specification string identifies a program to be executed on the remote 
node. For example: 

BOSTON: : "TASK=TEST2" 

The preceding specification identifies the program TEST2 on the remote node 
BOSTON. You can use task specification strings within a program to enable 
the program to communicate with another program on a remote node. 

For more information, see the DECnet for OpenVMS Networking Manual. 

4.1 .4.2 Specifying Access Control Strings 

The access control string designates an account you can log in to on the remote 
node. A node name with an access control string has the following format: 

node"access-control-string":: 

Enclose the access control string in quotation marks (" ") and follow it with a 
double colon (::). 
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On OpenVMS systems, the access control string consists of a user name, followed 
by one or more spaces or tabs and a password. For example: 

$ DIR B0ST0N"HIGGINS ETUHCARAP" : :WEASEL2 : [BORIS] ACCOUNTS .DAT 

Here, BOSTON is the network node name. "HIGGINS ETUHCARAP" is an 
access control string where: 

• H IGGI NS is a user name on the node BOSTON . 

• ETUHCARAP is the password associated with that name. 

For additional information on ACLs, see Chapter 18. 

4.2 Using Wildcards with File Names 

Use wildcard characters to apply a DCL command to multiple files rather than to 
one file at a time. The command applies to all files that match the portion of the 
file specification entered. 

With many DCL commands, you can use asterisks (*) and percent signs (%) 
as wildcard characters in directory names, file names, and file types. (Refer to 
Section 5.10 for information on wildcards used with directories.) You can also use 
an asterisk, but not a percent sign in version numbers. 

Many examples in this chapter show the use of wildcard characters in file 
operations. The use of wildcard characters in DCL commands varies with 
the individual command. For more information about using wildcards with a 
particular DCL command, seeth e OpenVMS DCL Dictionary. 

4.2.1 The Asterisk (*) Wildcard Character 

Use the asterisk wildcard character to match the following: 

• An entire field, or a portion of it, in the directory, file name, and file type 
fields 

• The entire version number field, but not a portion of it 

Wildcard characters let you manipulate large numbers of files without naming 
them individually. For example, the following file specification selects all versions 
of all files in the [FROGMAN] directory: 

$ PRINT [FROGMAN]*.*;* 

You can also limit the files selected to a more specific group. I n the following 
example, only those files in the current default directory with the file type .DAT 
are displayed: 

$ TYPE * . DAT ; * 

You can also use the asterisk wildcard (*) in a directory specification. The 
following example selects all files with the file type .DAT that exist in 
subdirectories one level below [FROGMAN]: 

$ DIRECTORY [FROGMAN. *]* .DAT 

Consider another example where wildcard characters appear in the directory 
specification: 

$ TYPE [*.*.*] AVERAGE . * ; * 

This file specification selects all versions of all files named AVERAGE, with 
any file type, that exist in any second-level subdirectory on the current default 
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disk. For example, this file specification selects [A. B.CjAVERAGE.DAT but not 
[X.YjAVERAGE.DAT. 

4.2.2 The Percent Sign (%) Wildcard Character 

Use the percent sign (%) wildcard character as a substitute for any single 
character in a file specification. You can use the percent sign in the directory, 
file name, and file type fields. You cannot, however, use the percent sign in the 
version number field or in ANSI magnetic tape file specifications. 

The following example displays the latest versions of all .DAT files whose names 
are DISTRICT followed by a single character: 

$ TYPE [JONES . TAXES . PROPERTY] DISTRICT% . DAT 

This display would includethefilesDISTRICTl.DAT, DISTRICT2.DAT, and 
DISTRICT3.DAT. The file DISTRICT4_5.DAT would not be displayed because it 
has more than one character after DISTRICT, nor would the file DISTRICT.DAT 
be displayed. The percent sign replaces one character position in a field, but 
there must be a character to replace. 

You can specify the percent sign as many times as necessary and in combination 
with other wildcard characters. For example, the following file specification is 
valid: 

$ [MA* ] INS%%%A* . J*; * 

4.3 Using Null File Names and File Types 

The file name and file type fields can be null. For example, the following are 
valid file specifications: 

.TMP (file name is null) 

TEMP. (file type is null) 

When you specify a file in a DCL command, be careful to omit the period following 
a file name if the command uses a default file type. For example, the FORTRAN 
command uses the default file type .FOR. The following commands produce 
different results: 

$ FORTRAN TEMP 
$ FORTRAN TEMP. 

In the first example, the FORTRAN compiler looks for a file named TEMP.FOR 
because the file type was omitted. I n the second example, the compiler looks for 
a file named TEMP, because a period following the file name indicates a null file 
type. 

4.4 Using Alternate File Names for Magnetic Tapes 

In addition to standard file names, the operating system supports an alternate 
file-naming convention for ANSI-labeled magnetic tapes. The format is as follows: 

"filename". [version 

The file name can contain 1 to 17 characters from the ASCI I "a" character set. 
This set of characters includes numeric characters, uppercase letters, and a space, 
as well as the following characters: 

In addition, asterisk (*) wildcards are allowed in ANSI file names. 
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4.5 Creating and Modifying Files 

The most versatile interactive tool for creating and modifying text files is the 
interactive text editor. EVE and EDT are two text editors that are included in 
the OpenVMS operating system; other text editors may also be available on your 
system. 

You can also create and modify files by using the DCL commands CREATE, 
COPY, and RENAME. The following sections describe how to create and modify 
files using these commands. 

4.5.1 Creating Files 

The CREATE command creates a text file. For example, to create a file named 
POUND. LIS, enter the CREATE command and then type lines of text: 

$ CREATE POUND. LIS 

Tag #23, Elmer Doolittle, notified 

Tag #37, James Watson, notified 

No tag, light brown, 30 lbs., looks part beagle 

| Ctrl/Z | 

Pressing Ctrl/Z signals the end of the file and returns you to DCL command level. 
You cannot modify a file with the CREATE command; after you have pressed 
Return, you cannot return to a previous line to modify a word. You must use 
a text editor such as EDT or EVE to modify a file created with the CREATE 
command. 

4.5.2 Copying Files 

The COPY command duplicates the contents of an existing file in a new file. For 
example, to copy FEES.DAT to RECORDS.DAT, enter the following command: 

S COPY FEES.DAT RECORDS.DAT 

The COPY command can duplicate many files at a time. For example, to copy 
all .TXT files in the default directory to another directory, enter the following 
command: 

$ COPY * . TXT ; * [SAVETEXT] * . *; * 

Use the /SINCE qualifier with the COPY command to select only those files that 
meet the specified criterion. For example, to copy to the default directory only 
those files in the directory U ONES. LICENSES. DOG] that have been modified 
since December 11, 1994, enter the following command: 

$ COPY/SINCE=ll-DEC-l 9 94 /MODIFIED [JONES . LICENSES . DOG] *. * * 

Concatenating Files 

The COPY command can concatenate files. For example, to append FEES1.DAT 
to FEES.DAT (forming a new version of FEES.DAT) in your default directory, 
enter the following command: 

$ COPY FEES. DAT, FEES1.DAT FEES.DAT 

Note that there is no space between the comma after FEES.DAT and the file 
name FEES1.DAT. 
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Copying Files from a Remote Node to Your Node 

Use the COPY command to copy files from another node to your node. For 
example, to copy the latest version of all files in DISK2:[PUBLIC] on node 
CHAOS to files with the same names in your default directory, enter the following 
command: 

$ COPY CHAOS: :DISK2: [PUBLIC]*.* * 

Copying Files from Your Node to a Remote Node 

Use the COPY command to copy files from your node to another node. For 
example, to copy the latest version of all files in your default directory to files 
with the same names in the directory DISK2:[STAFF_BACKUP] on nodeCHAOS, 
enter the following command: 

$ COPY *.* CHAOS: :DISK2: [STAFF_BACKUP] 

If you receive a protection violation or DECnet error message when you attempt 
to copy a file across systems, you have two recourses: 

• If the file is yours, you can use Mail to send it to a user account on the other 
node. For example, the following command sends the file FEES.DAT to the 

J ONES account on nodeCHAOS: 

S MAIL/SUBJECT="Fee schedule" FEES.DAT CHAOS:: JONES 

When sending files though mail, please note the following restrictions: 

When files are copied using the COPY command, the operating system 
performs data-integrity checking. This check does not occur when sending 
a file through mail and can cause corrupted files to occur when sending 
foreign (such as executable) files. 

Use discretion when sending large files. Users on some systems may not 
be able to receive large files (such as PostScript files). 

For more information on using Mail to send files, see Chapter 6. 

• You can follow the node name in the file specification with an access control 
string (see Section 4.1. 4.2). For example, if you have an account on node 
CHAOS with the user name SMITH and the password SPG96PRT, you can 
use the following command to copy files to that node: 

$ COPY *.* CHAOS "SMITH SPG96PRT" : :DISK2 : [STAFF_BACKUP] 

In this example, the user SMITH has WRITE access to the 
[STAF F_B ACK U P ]di rectory. 

4.5.3 Renaming Files 

Use the RENAME command to give the file a new name and optionally to locate 
it in a different directory. For example, to give the file FEES.DAT the new name 
RECORDS.DAT and move it from the default directory to another directory, enter 
the following command: 

$ RENAME FEES.DAT; 4 [ SAVETEXT ] RECORDS . DAT 

Note that after being renamed, the file FEES.DAT;4 no longer exists in the 
default directory. When you use the RENAME command, the input and output 
locations must be on the same device. 
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4.6 Displaying the Contents of Files 

To display the contents of a file on your screen, enter the TYPE command and the 
file name at the DCL prompt. For example, to display the latest version of the 
fileSTAFF_VACATIONS.TXT, enter the following command: 

$ TYPE STAFF_VACATIONS.TXT 

You do not have to specify the version number in the file specification because the 
system displays the latest version of a file by default. 

Controlling the Display 

To stop the scrolling of the text on the screen temporarily, press the FI old Screen 
key (FI on VT200 and VT300 series terminals); to resume scrolling, press the 
FI old Screen key again. To stop the display and return to DCL command level, 
press Ctrl/Y or Ctrl/O. 

If you specify the /PAGE qualifier to the TYPE command, you can view one screen 
at a time. The system prompts you to press Return when you want to see the 
next screen. 


Note 

By invoking an interactive text editor (for example, EVE or EDT) with 
the /READ_ONLY qualifier, you can use interactive editing commands to 
move around in a file and search for specific sequences of characters. The 
/READ_ONLY qualifier prevents you from creating a modified version of 
the file when you exit from the interactive editor. 


Displaying a File on a Remote Node 

To display the contents of a file on a remote node, include the node name, 
disk, and directory in the file specification. For example, to display the file 
COMPANY_HOLIDAYS.TXT, which is located on remote node CHAOS, enter the 
following command: 

$ TYPE CHAOS: :DISK2: [PUBLICICOMPANY_HOLIDAYS.TXT 

Displaying Files with Wildcards 

You can use the asterisk wildcard (* ) to display all versions of a specific file. For 
example, to display all versions of the file LOGI N .COM in the directory U ONES], 
enter the following command: 

$ TYPE [JONES] LOGIN.COM;* 

To display all versions and all file types of all files that begin with the word 
STAFF in the directory [J ONES], enter the following command: 

$ TYPE [JONES] STAFF*.*;* 

Displaying More Than One File 

If you specify more than one file in the TYPE command line, the system displays 
the files in the order you specify. If you use wildcard characters, the system 
displays the files in alphabetical order. 
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4.7 Deleting Files 

The DELETE command removes files from directories and releases the disk space 
they occupy for use by other files. When you use the DELETE command, you 
must specify a version number or the asterisk wildcard character as a version 
number in each file specification. For example, to delete version 17 of the file 
POUND. LIS, enter the following command: 

$ DELETE POUND. LIS; 17 

To delete versions 16 and 17 of the file POUND. LI S, enter the following command: 

$ DELETE POUND. LIS; 16, ; 17 

To delete all versions of the file POUND. LIS, enter the following command: 

$ DELETE POUND. LIS;* 

When you delete many files with wildcard characters, you might want to confirm 
each deletion by using the /CON FIRM qualifier. For example, to confirm the 
deletion of all the files in the subdirectory [J ONES. LICENSES. DOG], enter the 
following command: 

$ DELETE/CONFIRM *.*;* 

DISKI: [JONES. LICENSES. DOG] FEES. DAT; 4, delete? [N] : Y 
DISKI: [JONES. LICENSES. DOG] FEMALE. LIS; 6, delete? [N] : Y 
DISKI: [JONES. LICENSES. DOG]MALE.LIS; 3, delete? [N] : N 
DISKI: [JONES. LICENSES. DOG] POUND. LIS; 17, delete? [N] : Y 

Similarly, you might want to display the names of files as they are deleted. To do 
this, specify the /LOG qualifier with the DELETE command. For example, if you 
enter the command in the following example, the system displays the names of 
the files after they are deleted: 

$ DELETE/LOG *.LIS;* 

_%DELETE-I-FILDEL, DISKI : [JONES . LICENSES .DOG] FEMALE . LIS; 6 deleted (35 blocks) 
_%DELETE-I-FILDEL, DISKI : [JONES . LICENSES .DOG] MALE . LIS; 3 deleted (5 blocks) 
_%DELETE-I-FILDEL, DISKI : [JONES . LICENSES .DOG] POUND . LIS; 17 deleted (9 blocks) 

The PURGE command deletes all except the latest version of the specified file 
(or all files) in the default directory or any other specified directory. Purging old 
versions of files after updating them enables you to retain more free space on 
your disk. 

For example, to purge all except the latest two versions of each file in your 
default directory, enter the following command: 

$ PURGE/KEEP=2 

4.8 Protecting Files from Other Users 

To prevent other users from accessing your files, you can change the protection 
or modify the ACL of your files. To change the protection or modify the ACL of 
a file, you must own the file, have control access to the file, or have GRPPRV, 
SYSPRV, BYPASS, or READALL privilege. 

There are two types of file protection, default and explicit. When a file is created, 
it usually has the same protections as its parent directory; this is the default 
protection. If you create a file using the CREATE/PROTECTION command or 
if you change the protection on an existing file by issuing the SET SECURITY 
/PROTECTION command, you are using explicit file protection. 
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Note that to protect a file completely, you must apply the same or greater 
protection to the directory in which the file resides. See Chapter 5 for information 
on directory protection. For complete information on changing file protections, 
see Chapter 18. 

4.9 Printing Files 

To print a file or files, use the PRI NT command. The PRI NT command places 
your print job (all the files to be printed) in a list of jobs to be printed called a 

print queue. 

For example, to place a print job containing three files in the default print queue, 
SYS$PRINT, enter the following command: 

S PRINT POUND, MALE, FEES. DAT 

Job POUND (queue SYS$PRINT, entry 202) started on SYS$PRINT 

The file types of the files named in the PRI NT command default to .LI S or the 
last explicitly named file type; thus, the preceding example queues POUND. LIS, 
MALE. LI S, and FEES.DAT to SYS$PRI NT. The system displays the job name 
(POUND), the queue name (SYS$PRI NT), and the job number (202). The system 
also indicates the status of the job. By default, the job name is the name of the 
first (or only) file specification in the PRI NT command. After a job is submitted 
to a queue, you reference it using the job number. After the job is queued, it will 
be printed when no other jobs precede it in the queue and when the printer is 
physically ready to print. 

A print queue can execute only one job at a time. Print jobs are scheduled for 
printing according to their scheduling priority, and the job with the highest 
priority is printed first. If more than one job exists with the same priority, the 
smallest job is usually printed first. J obs of equal size having the same priority 
are selected for printing according to their submission time. Priority may also 
be determined by the system manger or by entering the /PRIORITY qualifier 
to the PRINT command. For more information on scheduling priorities, seethe 
OpenVMS System Manager's Manual. 

4.9.1 Displaying Queue Information 

The default print queue, SYS$PRINT, is usually started as part of the site-specific 
system startup procedure. To display the queues at your site, enter the SHOW 
QUEUE command as follows: 

S SHOW QUEUE 

To display the status of your print jobs, enter the SHOW ENTRY command as 
follows: 

$ SHOW ENTRY 

The system displays the following list: 

Entry Jobname Username Blocks Status 


202 POUND JONES 38 Pending 

On stopped printer queue SYS$PRINT 

To see jobs queued by other users, specify the USERNAME parameter to the 
SHOW ENTRY command. To see information about a specific job or jobs, specify 
the entry number or job name parameter. 
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4.9.2 Print Forms 

A print form serves the following functions: 

• Determines certain page formatting attributes (such as margins and page 
length) 

• Determines whether a job is eligible to print depending on the paper stock 
specified in the form 

If your printing needs are limited, you do not need to use special forms; Digital 
supplies a systemwide default form (named DEFAULT) for all queues. System 
managers can also create print forms. If you need to format output or if certain 
print jobs require special paper, contact your system manager. 

4.9.3 Stopping and Deleting a Print Job 

To stop a print job and delete it from the print queue, enter the entry number 
parameter to the DELETE/ENTRY command. For example, to delete entry 202, 
enter the following command: 

$ DELETE/ENTRY=202 

4.9.4 Printing a File on Another Node 

To print a file on another system, copy that file to the remote node and specify 
the /REMOTE qualifier to the PRI NT command. For example, to copy the file 
COMPANY_FIOLIDAYS.TXT from your local node to the remote node CHAOS 
and queue the file for printing to the default system print queue (SYS$PRI NT) on 
node CHAOS, enter the following commands: 

$ COPY C0MPANY_H0LIDAYS.TXT CHA0S"J0NES PANDEMONIUM" : :DISK2 : [JONES] * 

$ PRINT/REMOTE CHAOS :: DISK2 : [JONES] C0MPANY_H0LIDAYS . TXT 

In this example, an access control string indicates that the user J ONES is 
authorized to copy files to the directory [j ONES] on node CHAOS. The asterisk 
wildcard at the end of the file specification instructs the system to duplicate the 
file nameCOMPANY_HOLIDAYS.TXT when that file is copied to the remote 
node. 

Note 

Not all qualifiers to the PRINT command are compatible with the 
/REMOTE qualifier. For example, you cannot queue a job to a specific 
print queue; all jobs are queued to the default system print queue 
(SYS$PRI NT). See the description of the /REMOTE qualifier to the DCL 
command PRINT in the OpenVMS DCL Dictionary for a list of PRINT 
command qualifiers compatible with /REMOTE. 


4.9.5 Summary of DCL Commands That Control Print Jobs 

The DCL commands listed in Table 4-3 allow you to control print jobs in various 
ways. For example, you can specify the number of copies printed or you can 
request that the system notify you when your print job is complete. 

In addition to the qualifiers listed here, if you are running DECprint Supervisor 
software on your system, you can use the /PARAMETER qualifier to print 
landscape, two-sided, or many other ways. Contact your system manager for 
a list of print options that are available on your system. For more information 
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on any of these commands, see the descriptions of the DCL commands in the 
OpenVMS DCL Dictionary or refer to DCL Help. 

Table 4-3 DCL Commands That Control Print Jobs 


Print Operations 

Print Job Commands and Qualifiers 

Number of copies 

By job 

By file 

Specified file only 

Number of pages 

PRINT/J OB COUNTS 1 

PRI NT/COPI ES^n 1 
file-spec/COPIES^n 1 

PRINT/PAGES^ 

Print features 

Flag pages 

Type of forms (paper) 
Special features 
Double-spacing 

Page heading 

Notification of job execution 

PRINT/FLAG^ 

PRINT/FORM^ 1 

PRINT/CHARACTERISTICS^ 

PRINT/SPACE 1 

PRINT/HEADER 1 

PRINT/NOTIFY 

Delay execution of a job 

For a specified time 

1 ndefinitely 

Release a delayed job 

Display your print jobs 

PRINT/AFTER 

PRINT/HOLD 

SET QUEUE/ENTRY /RELEASE 

SHOW ENTRY 

Stop a print job 

Delete job 

Stop currently printing 
job and begin printing 
the next job in the 

DELETE/E NTRY =job-number 

STOP/ABORT 

queue 

Stop currently printing 
job and requeue it for 
printing 

STOP/REQUEUE 

Keep a job in a queue 
after it has completed 

PRINT/RETAIN 


Parallel qualifiers for the SET QUEUE/ENTRY command allow you to specify these operations for 
print jobs that are already queued but not yet printing. 
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Directories are files that store the names of files. This chapter describes how to 
use directories to organize and manage files. 

For more information on the DCL commands described in this chapter, refer to 
DCL Help or see the OpenVMS DCL Dictionary. 

Note 

Throughout this chapter, examples that specify a node name do not 
always include an access control string. This is because proxy accounts 
enable users to perform operations on the remote systems in these 
examples. 


5.1 Understanding Directory Structures 

Figure 5-1 shows a sample directory hierarchy. At the top of the structure is the 
master file directory (MFD). Its directory name is [000000], The MFD shown in 
Figure 5-1 contains entries for user file directories including MARTI NO. Dl R, 
PUBLIC. Dl R, and J ONES.DI R. The top-level directory [) ONES] is a user file 
directory named J ONES.DI R;1 in [000000], 
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Figure 5-1 Directory Structure 


Master File 
Directory (MFD): 


Top Level Directory: 


Second Level Directory: 


Third Level Directory: 


[ 000000 ] 
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Assume that you are user J ONES. When you log in, the system places you 
in [J ONES], your default directory. [JONES] contains the following four 
nondirectory files: 

• LOGI N .COM ;3 

• LOGI N .COM ;4 

• STAF F.DI S;3 

• STAFF_VACATIONS.TXT 

U ONES] also contains the following two directory files: 

• LICENSES. DIR 

• TAXES. DIR 

The directory file LICENSES. Dl R;1 points to the [J ONES. LICENSES] 
subdirectory; TAXES. Dl R;1 points to the [J ONES.TAXES] subdirectory. 
(Subdirectories are specified by concatenating the subdirectory name to the 
name of the directory one level above it.) 

The [J ONES. LICENSES] subdirectory contains three nondirectory files 
and two directory files. The directory file DOG.DIR;l points to the 
U ONE S.L I CENSES. DOG] subdirectory; MARRI AGE.DI R points to the 
0 ONES. LICENSES. MARRIAGE] subdirectory. 
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This sample directory structure is the basis for many of the examples in this 
chapter. 

5.2 Understanding Directory Names and Specifications 

Use a directory specification to refer to a directory. A directory specification 
consists of a top-level directory name that can be followed by a maximum of seven 
subdirectory names. Subdirectory names are always preceded by a period ( . ). 

A directory specification has the following format: 

[d i recto ry. s u bd i recto ry] 

To add one or more levels of subdirectories, add a period and another subdirectory 
name for each subdirectory (up to seven levels): 

[d i recto ry. s u bd i recto ry. s u bd i recto ry] 

A directory or subdirectory name can contain up to 39 alphanumeric characters. 
Any characters valid for file names are also valid for directory names. Enclose 
the directory name in either square brackets ([ ]) or angle brackets ( < >). 

5.3 Creating Directories 

To create a directory, enter the CREATE/DIRECTORY command. For example, to 
create a directory [J ONES. LICENSES], enter the following command: 

$ CREATE/DIRECTORY [JONES .LICENSES] 

If you want to create a subdirectory under your current directory, you do not 
have to specify the current directory name; you can enter the subdirectory name 
preceded by a period. For example, if your current default directory is U ONES], 
enter the following command: 

$ CREATE/DIRECTORY [.LICENSES] 

5.4 Displaying Directories 

To display the names of files in a directory, enter Dl RECTORY at the DCL 
prompt. For example, to list the files in |J ONES], enter the following command: 

$ DIRECTORY 

The system displays the contents of [J ONES] as follows: 

Directory DISKI : [JONES] 

LICENSES. DIR; 1 
LOGIN.COM; 3 
LOGIN.COM; 4 
STAFF. DIS; 3 
STAFF_VACATIONS . TXT; 2 
TAXES. DIR; 1 

Total of 6 files. 

This example shows that [J ONES] contains two subdirectories, 

U ONES. LICENSES] and [J ONES.TAXES], four nondirectory files, STAFF. DIS, 
STAFF_VACATIONS.TXT, and two versions of LOGIN.COM. 

To list the files in a subdirectory, enter the Dl RECTORY command and the 
subdirectory name preceded by a period. For example, assuming that the 
default directory remains [J ONES], to list the contents of the subdirectory 
U ONES.LICENSES], enter the following command: 
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$ DIRECTORY [.LICENSES] 

The system displays the contents of [.LICENSES] as follows: 

Directory DISKI : [JONES. LICENSES] 

DEPT.DAT; 3 
DOG. DIR; 1 
MAILING. LIS; 6 
MARRIAGE. DIR; 1 
T0TAL.DAT; 2 

Total of 5 files. 

When you include certain command qualifiers along with the DIRECTORY 
command, you can retrieve information in addition to the names of the files. See 
the OpenVMS DCL Dictionary for a list of qualifiers that can be used with the 
DIRECTORY command. 

5.5 Setting a Default Directory 

To change your default directory, use the SET DEFAULT command. The new 
default remains in effect until you enter another SET DEFAULT command or log 
out. 

For example, to set default to the directory [| ONES] and then display the file 
U ONESJSTAFF_VACATIONS.TXT, enter the following commands: 

$ SET DEFAULT [JONES] 

$ TYPE STAFF_VACATIONS.TXT 

To set default to a subdirectory, append the subdirectory name to the name of 
the directory one level above it. For example, to display the file Bl LLI NG.DAT 
located in the subdirectory U ONES.TAXES], enter the following commands: 

$ SET DEFAULT [JONES . TAXES] 

$ TYPE BILLING.DAT 

To display your current default directory, enter the command SHOW DEFAULT, 
as shown in the following example: 

$ SHOW DEFAULT 

DISKI: [JONES. TAXES] 

$ SET DEFAULT [PUBLIC] 

$ SHOW DEFAULT 
DISKI: [PUBLIC] 


5.6 Setting a Default Device 

Section 5.5 describes how to set a default directory with the DCL command SET 
DEFAULT. You can also use the SET DEFAULT command to change the default 
device. The default remains in effect until you enter another SET DEFAULT 
command or log out. 

The following example shows how to change the default device: 

$ SHOW DEFAULT 
DISKI: [JONES] 

$ SET DEFAULT DISK2 : [GROUP] 

$ SHOW DEFAULT 
DISK2 : [GROUP] 
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You can specify the device to which you want to set default without including the 
directory in the command. I n the following example, the directory [J ONES] is 
assumed and exists on Dl SKI and Dl SK2: 

$ SHOW DEFAULT 
DISKI : [JONES] 

$ SET DEFAULT DISK2 : 

$ SHOW DEFAULT 
DISK2 : [JONES] 

Note that the operating system allows you to set default to a nonexistent disk 
or directory. If you have set default to a nonexistent directory, when you try to 
manipulate a file, the system displays a message stating that the directory does 
not exist. If you find yourself in a nonexistent disk or directory and cannot carry 
out a desired operation, set default to an existing disk or directory. 

5.7 Using Temporary Defaults 

If you enter a list of files and do not give a complete file specification for each file 
in the list, the system applies temporary defaults for node names, device names, 
and directory names. For example, the following command copies A. LIS and 
B.LI S from the [STATS] directory to the [RESULTS] directory: 

$ COPY [STATS] A. LIS, B . LIS [RESULTS] 

I n this example, [STATS] is the temporary default directory for the file B.LI S. 
The system uses the preceding file specification in the list ([STATS]A.LI S) to 
determine the default directory. The following command uses a temporary default 
device and two different directories: 

$ COPY BASE: [STATS] A. LIS, [TIME]B. LIS, C. LIS [RESULTS] 

I n this example, all three files (A. LI S, B.LI S, and C.LI S) are copied from the 
BASE device. The A.L I S file is copied from the [STATS] directory. The other two 
files are copied from the [Tl ME] directory. 

To substitute your current default directory for a temporary default, use empty 
square brackets. For example, if the current default directory is [BETA], the 
following command copies [ALPHA]TEST.DAT and [BETA]FI NAL.DAT to the 
[RESULTS] directory: 

$ COPY [ALPHAJTEST.DAT, [] FINAL. DAT [RESULTS] 

If you include a node name in a file that appears in a list, you can override the 
temporary default by using a double colon. 

5.8 Deleting Directories 

To delete a directory, use the following procedure: 

1. Make sure that the directory contains no files. To find out if the directory 
contains files, enter the DIRECTORY command, as shown in the following 
example: 

$ DIRECTORY 

When there are no files in the directory, the system displays the following 
message: 

%DIRECT-W-NOFILES, no files found 
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If the directory contains files, copy them to another directory to save them 
or delete them if you do not want to save them. If the directory contains 
subdirectories, examine those subdirectories, copy or delete their files, and 
delete the subdirectories. 

2. M ove to the directory one level above the directory you want to delete. For 
example, if you want to delete [| ONES. LICENSES], you should set default 
to [J ONES], Remember that the subdirectory U ONES.LICENSES] exists as 
a file named LICENSES.DIR;1 in the directory U ONES], When you delete a 
directory, you delete the file that points to that directory. 

3. Change the file protection of a directory to allow delete access to the file. (See 
Chapter 4 for more information about file protection.) For example, to change 
the file protection of LICENSES. Dl R, enter the following command: 

S SET SECURITY/PROTECTION=OWNER: D LICENSES. DIR 

4. Delete the directory file. For example, to delete the directory file LI CENSES, 
enter the following command: 

$ DELETE LICENSES. DIR;* 

The following example shows how to delete the subdirectory [J ONES.LICENSES]: 

$ SET DEFAULT [JONES . LICENSES] 

$ DIRECTORY 

%DIRECT-W-NOFILES, no files found 
$ SET DEFAULT [JONES] 

$ SET SECURITY/PROTECTION=OWNER: D LICENSES. DIR 
$ DELETE LICENSES. DIR; 1 

The directory files (for example, J ONES.DIR;l) in the master file directory 
require SYSPRV privilege to delete. Seeth eOpenVMS System Manager's Manual 
for a discussion of user privileges. 

5.9 Protecting a Directory from Other Users 

You cannot completely protect a file without applying at least the same protection 
to the directory in which the file resides. For example, if you deny a user all 
access to a file but allow that user read access to the file's directory, the user 
cannot access the contents of the file but can see that it exists. Conversely, a 
user allowed access to a file and denied access to the file's directory (or one of the 
parent directories) cannot see that the file exists. 

Note 

To protect sensitive files, directory protection alone is not adequate. You 
must also protect each file within the directory. 


By default, top-level directories receive UlC-based protection 
(S:RWE,0:RWE,G:RE,W:E) and no ACL. Subdirectories receive UlC-based 
protection from the parent directory. For more information on protection codes, 
see Section 18.2.3. 

To specify UlC-based protection explicitly when creating a directory, use the 
/PROTECTION qualifier with the CREATE/DI RECTORY command. You cannot 
specify an ACL for the directory until the directory is created. To change 
the UlC-based protection of an existing directory, apply the SET SECURITY 
/PROTECTION command to the directory file. 
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You can limit but not prohibit directory access by specifying execute access but 
not read access. Execute access on a directory permits you to examine and read 
files that you know are contained in the directory; that means you can examine 
a file if you already know what the file specification is, but you cannot display a 
list of the files in the directory. For additional security information s eeOpenVMS 
Guide to System Security. 

5.10 Using Wildcards to Search the Directory Structure 

From any point in a directory structure, you can refer to another directory or 
subdirectory in the structure. Do this by specifically naming the directory or 
subdirectory you want or by using the ellipsis ( ... ) and hyphen (-) wildcard 
characters. For additional information about wildcards, see Section 4.2. 

5.10.1 The Ellipsis (...) Wildcard Character 

Use the ellipsis (...) wildcard character to search down into the directory 
hierarchy. To search the current directory and all the subdirectories below it, use 
the ellipsis by itself as shown in the following command: 

$ DIRECTORY [ . . . ] 

For example, assuming the current directory is U ONES], to display the latest 
versions of all files named FEES.DAT in [| ONES] and all subdirectories under 
U ONES], enter the following command: 

$ TYPE [JONES. . . ] FEES. DAT 

If you begin the directory specification with an ellipsis, the search begins from 
your current directory. For example, assuming the current default directory is 
U ONES], to search all subdirectories that end in .SALES and display the latest 
versions of the file FEDERAL. LI S, enter the following command: 

S TYPE [.. .SALES] FEDERAL. LIS 

The following command displays the latest versions of all files named DEPT.DAT 
in U ONES] and all subdirectories under [J ONES]: 

$ TYPE [ . . .] DEPT.DAT 

Flowever, if you begin the directory specification with a period, only the 
subdirectory that is one level lower than the current directory is searched. 
Assuming the current directory is 0 ONES], the following command searches 
only the [.LICENSES] subdirectory that is one level lower than U ONES] for 
the file MAILING. LIS. The subdirectory [J ONES. LICENSES] is searched, but 
[J ONES. LICENSES. MARRIAGE] is not: 

$ TYPE [ ,LICENSES]MAILING.LIS 

Assuming the current directory is [J ONES], the following command displays the 
latest versions of all files named DEPT.DAT in the [.LICENSES] subdirectory 
under [JONES] and all subdirectories under the [.LICENSES] subdirectory: 

$ TYPE [...LICENSES...] DEPT. DAT 

To search all top-level directories and their subdirectories from wherever you are 
in the directory structure, use an asterisk (* ) followed by an ellipsis ( ... ). The 
following command, which requires READALL privilege, searches as many as 
eight levels of directory names (the top-level directory and seven subdirectories), 
if they exist. It does not search the MFD. 

$ DIRECTORY [*...] 
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5.10 Using Wildcards to Search the Directory Structure 

5.10.2 The Hyphen (-) Wildcard Character 

Use the hyphen (-) wildcard character to move up through the directory 
structure. Each hyphen refers to the directory one level up from the current 
one. You can follow the hyphens with directory and subdirectory names to move 
down the directory structure on another path. 

For example, if your current directory is [J ONES. LICENSES], enter the following 
command to display the latest version of STAFF.DIS in U ONES]: 

$ TYPE [-] STAFF.DIS 

If your current directory is [J ONES. LICENSES], enter the following command to 
display the latest version of Bl LLI NG.DAT in [J ONES.TAXES]: 

$ TYPE [- . TAXES] BILLING.DAT 

You can specify more than one hyphen. The following command moves you up 
two levels in the directory hierarchy: 

$ SET DEFAULT [ — ] 

If you enter so many hyphens that you point above the top-level directory, the 
system displays an error message. 

5.11 Working with Directories in UIC Format 

Although this chapter focuses on how to use named directories, you can also 
specify directory names in UIC format. In UIC format, a 2-part octal number 
forms a user identification code (UIC) that refers to a user file directory (UFD). 
Almost every DCL command that accepts a file specification can recognize 
directory names in UIC format. In general, you do not need to use this format 
unless you are working with a real-time Resource Sharing Executive (RSX) 
operating system. 

A UIC directory specification has the following format: 

[group, member] 

For example, [122,1] is a UIC directory specification representing member 1 
in group 122. Directory names in UIC format generally, but not necessarily, 
correspond to the U I C of the owner of the directory. 

When you refer to a UIC directory, observe the following rules: 

• Use an octal number in the range of 1 to 37776 to specify the group. 

• Use an octal number in the range of 0 to 177776 to specify the member. 

• Do not use the hyphen (-) or ellipsis (...) wildcard as part of the 
specification. 

It is also possible to use the asterisk (* ) wildcard to specify a UIC directory. For 
example, [*,6] indicates all directories with any group number and a member 
number of 6. The search is limited to directories in UIC format. The directory 
specification [*,*] locates all directories in UIC format. To locate all named 
directories as well as all directories in UIC format, use [*]. 
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Note that you can translate a directory name in UIC format to named format. 

If necessary, add zeros to the left of the group and member numbers to create 
a 6-character name. For example, the named equivalent of the UIC directory 
specification [122,1] is as follows: 

[ 122001 ] 

You cannot combine UIC format and named format. If you have a directory with 
a name in UIC format and you want to specify one of its subdirectories, translate 
the UIC format to named format. For example, to refer to the subdirectory 
[122,1]SUB.DI R, use the named directory [122001. SUB], 
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The OpenVMS Mail utility (M Al L) lets you send messages to other users on 
your system or on any other computer that is connected to your system with the 
DECnet for OpenVMS network. This chapter describes the routine tasks you can 
perform using Mail and how you can customize Mail to fit your needs. 

For more information about Mail commands and qualifiers, type HELP at the 
MAIL> prompt. For information on controlling the use of Mail through user 
accounts, see the OpenVMS System Manager's Manual. Figure 6-1 shows a 
sample mail message and its components. 

Figure 6-1 Sample Mail Message 


Message Number Date Time 


Folder Name 


Address 
Information 
Subject Prompt - 


{ 


# 1 11— DEC— 1994 14:12:27 

From: STONE: : FELLINI 

To : JONES 

Subj: Sales presentation on April 20 


NEWMAIL 


The meeting to discuss the Hubbub Cola account has been 
moved from our conference room to the auditorium. 


Message 

Text 


< 


MAIL Prompt ■ 


See you there ! 
Joe 
MAIL > 


ZK-0980A-GE 


6.1 Invoking and Exiting Mail 

To invoke the Mail utility, enter the DCL command MAI L, as follows: 

$ MAIL | Return | 

MAIL> 

Once you are in the Mail utility, you can enter Mail commands by typing a 
command at the M Al L> prompt and pressing either the | Return | or | Enter | key. 

By entering Mail commands at the MAI L> prompt, you can do the following: 

• Read a mail message 

• Send a mai I message 
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• Reply to a mail message 

• Forward a mail message 

• Organize mail messages into files and folders 

• Delete a mail message 

• Print a mail message 

The remaining sections in this chapter describe these tasks and provide examples 
for performing them. Table 6-1 lists and describes all the Mail commands. For 
a complete description of Mail commands and their qualifiers, invoke Mail and 
enter the HELP command. 

To exit from Mail, enter the EXIT command at the MAI L> prompt, as follows: 

MAIL> EXIT [Return] 

$ 

You can also exit from Mail by pressing Ctrl/Z or by using the QUIT command. 

6.2 Reading Messages 

Mail stores the messages you receive in mail files, which have the default file type 
.MAI. In this file, by default, Mail provides two folders that store old and new 
messages. New messages are automatically placed in a folder called NEWMAIL; 
old messages are placed in a folder called MAI L. After you read a new message, 
the message automatically moves from the NEWMAI L folder to the MAI L folder, 
unless you enter the FILE, MOVE, or DELETE command. Mail deletes the 
NEWMAIL folder after you have read all new mail messages and either select 
another folder or exit from Mail. 

The following sections describe how to read new and old mail messages. 

6.2.1 Reading a New Message 

When you are logged in to your account and receive a mail message, Mail notifies 
you. For example, notification of a message sent by user FELLINI is displayed as 
follows: 

New mail on node DOODAH from STONE: : FELLINI (10:02:23) 

To read a new message, invoke Mail and press the Return key at the MAIL> 
prompt, as follows: 

$ MAIL 

You have 1 new message. 

MAIL> | Return | 

If you have more than one new message, press Return at the M Al L> prompt 
to read the other messages. When you have read all your new messages, Mail 
issues the message "%MAI L-E-NOMOREMSG, no more messages” and continues 
to prompt for commands until you exit Mail. 

If you receive a mail message while you are in Mail, enter the READ/NEW 
command to read the new message. 
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6.2.2 Reading Old Messages 

To reread old mail messages in your default Mail folder, use the following 
procedure: 

1. Enter the SELECT command at the MAI L> prompt: 

MAIL> SELECT MAIL [FteST] 

Mail places you in the folder named MAIL. 

2. To read the first message in your default MAI L folder, press Return at the 
MAI L> prompt or enter the READ command. 

Mail displays the first message (1) in your default mail file. 

3. To display the next message, press Return. 

4. If the message is too long to display on one screen, press Return to display 
the next part of the message. 

5. To skip the remainder of a message and display the next message, enter 
NEXT. 


To read a particular message in your default MAIL folder, use the following 
procedure: 

1. Enter the Dl RECTORY command at the MAI L> prompt: 

MAIL> DIRECTORY [FtetUFiT] 

Mail displays a list similar to the following: 


MAIL> DIRECTORY [Return] 

# From Date 

1 STONE : :FELLINI ll-DEC-1994 

2 DOODAH: : JONES ll-DEC-1994 


MAIL 

Subject 

Sales presentation on December 11 
Status 


MAIL> 


To select a subset of messages from the list, use the Dl RECTORY command 
qualifiers /FROM or /SUBJ ECT. (For more information, enter the HELP 
Dl RECTORY command at the MAI L> prompt.) 

2. Enter the number of the message you want to read at the M Al L> prompt. 

MAIL> 2 [Rejum] 

Mail displays the message that you selected. 

If you have many messages, you can locate a particular message by using the 
SEARCH command to find a string in one or more of the messages. To search for 
a string, specify that string as a parameter to the SEARCH command, as shown 
in the following example: 


MAIL> SEARCH "appointment" | Return | 

The SEARCH command selects and displays the first message in the current 
folder that contains the string appointment. 

To search for a new string, specify the string as a parameter to the SEARCH 
command. Each time you specify a new string, the SEARCH command starts 
the search at message number 1. To continue searching the folder for messages 
that contain the specified string, use the SEARCH command without specifying a 
parameter. To search for the same string in a different folder, enter the SELECT 
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or SET FOLDER folder-name command and continue using the SEARCH 
command without specifying a parameter. 

6.3 Sending a Message 

To send a mail message to any user on your system, do the following: 

1. Enter SEND at the MAI L> prompt: 

MAIL> SEND [Return] 

To: 

M ail prompts you for the name of the user to receive the message. 

2. Enter the name of the user receiving the message and press Return. 

To: THOMPSON [Return] 

Subj : 

M ail prompts you for the subject of the message. 

3. Enter the subject of the message and press Return. Entering this information 
is optional. 

Subj: Meeting on April 20 | Return | 

Enter your message below. Press CTRL/Z when complete, or CTRL/C to quit: 

M ail prompts you for the text of the message. 

4. Enter the text of a message, or just press Return. Entering this information 
is optional. 

I have some new ideas about the Hubbub Cola account. Let me know | Return | 
when you are available to talk about them. | Return | 

| Return] 

—Jeff 

5. Press Ctrl/Z to send the message. If you decide not to send the message, 
press Ctrl/C, which cancels the send operation without exiting from Mail. 

6.3.1 Sending Mail over the Network 

If your computer system is part of a network, you can send mail to any other user 
on the network. If you are sending mail to someone on a different node, enter the 
user's node name and user name at the To: prompt. If the user name contains 
special characters or spaces, you must enclose the user name in quotation marks. 
Use the following format: 

nodenamecusername 

For additional information on specifying node names, refer to Section 4.1.2. 

For example, to send a message to user HIGGI NS on node CH EETA, enter the 
following command and user name: 

MAIL> SEND iFtetJFEI 

To: CHEETA: : HIGGINS [Return] 

Mail displays a message if the network connection to the remote node is not 
available. Wait a while, and try to send the message later. 

You can use a logical name to represent a user's name and node. For example, 
to use the name H ENRY in place of CH EETA::H I GGI NS, define the name as 
follows: 
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$ DEFINE HENRY CHEETA: : HIGGINS 

You can then use the logical name to send mail. For example: 

$ MAIL | Return | 

To: HENRY [Rgjjjm] 

Note that Mail ignores any access control information in the node name or logical 
name. 

6.3.2 Sending a Message to More Than One User 

You can send mail to several users at the same time in one of two ways: using 
individual user names at the To: prompt or using a distribution list. 

To send the same message to several users on the same node by using their user 
names, enter the user names at the To: prompt and separate them with commas 
or spaces. For example, to send a message to Thompson, J ones, and Barney, enter 
the following: 

MAIL> SEND [Return] 

To: THOMPSON, JONES, BARNEY [FtetUTiTj 

Subj : Meeting on January 9 | Return | 

Creating a Distribution List 

A distribution list is a file that contains a list of users and their node names. 

You must use a text editor to create distribution lists. Distribution lists are not 
created within the Mail utility. 

To create a distribution list, use the following procedure: 

1. Use a text editor to create a distribution list file with the file type .Dl S. 

2. Type one user name per line in the file. 

3. To include the names of other distribution lists in the file (to "nest" the lists), 
specify an at sign (@) followed by the name of the distribution list. 

Your open file quota (a limit associated with your account) determines the 
number of different nodes to which you can send mail (at one time) and the 
depth to which you can nest distribution lists. If you exceed the quota, Mail 
displays an error message. Ask your system manager to increase your quota, 
or send mail in batches to fewer nodes at one time. 

4. To include comments in the file, enter an exclamation point ( ! ) before the 
comment. 

The following example shows a distribution list file: 

! ALLBDDGET.DIS 
1 

! Budget Committee Members 

0BUDGET ! listed in BUDGET. DIS. 

! Staff 
Thompson 
BRUTUS : : JONES 
PORTIA: : BARNEY 

I n the preceding example, if the file BUDGET.DI S is not in the same directory as 
the new distribution list file you are creating (ALLBUDGET.DI S), include the file 
specification for BUDGET.DI S in the new distribution file. Depending on where 
you create ALLBUDGET.DIS, you might have to specify the device and directory 
in which BUDGET.DI S is located. (See Chapter 4 for more information about file 
specifications.) 
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Sending a Message to a Distribution List 

To send mail to several users by using a distribution list, use the following 
procedure: 

1. Invoke Mail. 

2. Enter SEND at the MAI L> prompt and press Return. 

MAIL> SEND |~RetunT| 

3. Enter an at sign ( @) and the file name of the distribution list at the To: 
prompt. Press Return. 

To: 0ALLBUDGET [rEM 

4. Enter the subject of the message at the Subj: prompt and press Return. 

Subj : Tomorrow' s Meeting | Return | 

5. E nter the text of the message at the text prompt. 

Enter your message below. Press CTRL/Z when complete, or CTRL/C to quit: 

The meeting about the Hubbub Cola account is tomorrow at 2:00. | Return | 

— Jeff | Return | 

By default, the system looks for a distribution list file with the file type .Dl S. If 
the file containing your distribution list has a different file type, specify the file 
name and file type at the To: prompt. If you invoke Mail while in one directory 
and the file containing the distribution list is in another, enter the distribution 
list's full directory name at the To: prompt. 

You can also send a file to a distribution list from DCL level. The following 
example sends the file M EETI NG.TXT to the user THOMAS and the distribution 
list FRIENDS. DIS: 

$ MAIL/ SUBJECT="for your information" MEETING THOMAS, "0FRIENDS. DIS" [RgUmJ 

If you omit the file type .Dl S, place quotation marks around the at sign and file 
name to identify the file as a distribution list. For example: 

$ MAIL NOTICE "0WRITERS" iRitUFE] 

This example sends the file NOTI CE.TXT to the distribution list WRITERS.DI S. 
Here, the /SUBJ ECT qualifier is not included so the message is sent without a 
subject notation. To include a subject, use the /SUBJ ECT qualifier to the MAIL 
command. For more information on sending mail from the DCL level, enter the 
HELP MAIL command at the DCL prompt. 

6.3.3 Sending a File 

You can send a file to other users from within Mail or from DCL level. If the 
file is a compound document structured according to the DIGITAL Document 
Interchange Format (DDI F) specification, Mail preserves the OpenVMS RMS file 
tags and DDIF semantics. 1 


1 For OpenVMS AXP Version 1.0 or VAX VMS Version 5.2-2 or later systems only. If 
you try to send mail messages containing DDI F files to operating systems other than 
OpenVMS or to OpenVMS systems earlier than OpenVMS AXP Version 1.0 or VAX VMS 
Version 5.2-2, Mail returns an error message. 


6-6 


Mail: Communicating with Other Users 
6.3 Sending a Message 

Use the following procedure to send a file from within Mail: 

1. At the MAIL>prompt, enter SEND and the name of the file you want to send. 

MAIL> SEND MEMO . TXT [Return] 

2. At the To: prompt, enter the user name of the person you want to receive the 
file. 

To: EDGELL I Return I 

3. AttheSubj: prompt, enter the subject of the file. 

Subj : Another memo | Return | 

4. To send the file, press Return; to cancel the send operation, press Ctrl/C or 
Ctrl/Y. Ctrl/C keeps you within Mail; Ctrl A' returns you to DCL level. 

When you send a file from DCL level, Mail is invoked but you do not enter an 
interactive session, nor do you see the MAI L> prompt. When the file is sent, you 
automatically return to DCL level. When you are sending a file from DCL level, 
the argument to the optional /SUBJ ECT qualifier must be enclosed in quotation 
marks if it contains any spaces or nonalphanumeric characters. 

For example, to send the file MEMO.TXT to user EDGELL on node CHEETA at 
DCL level, use the following procedure: 

1. At the DCL prompt, enter the following command: 

$ MAIL/ SUB JECT=" Another memo" MEMO.TXT CHEETA: : EDGELL |Retun7[ 

2. Press Return to send the file; press Ctrl/C to cancel the send operation. 

No wildcard characters are allowed in the file specification. If you omit the file 
type, the default file type is .TXT. 

If you specify SYS$I NPUT as the file specification, you are prompted for the text 
of the message (while still remaining at the DCL level), as the following example 
shows: 

S MAIL SYS$INPUT : [rSuTT] 

To: ARMSTRONG [Return] 

Enter your message below. Press CTRL/Z when complete, or CTRL/C to quit: 

The text of the message is here. 

| Ctrl/Z | 

$ 

For more information on using SYS$INPUT, see Chapter 13. 

At the To: prompt, specify the name of one or more users or a distribution list. 

6.3.4 Creating a File from a Message 

To create a text file from a message, enter the EXTRACT command and the file 
name at the MAI L> prompt while you are reading the message. For example, 
to create a file named DEC_MEETINGS.TXT from the following mail message, 
enter the EXTRACT command as shown at the end of the following example: 
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#1 01-DEC-1994 14:12:27 NEWMAIL 

From: STONE: : FELLINI 
To: Thompson 

Subj: Dates for December sales meetings 

Sales meetings in December will be held on the following dates: 

Wednesday Dec. 8, 1994 
Tuesday Dec. 14, 1994 
Monday Dec. 20, 1994 
Thursday Dec. 30, 1994 
MAIL> EXTRACT DEC_MEETINGS.TXT [RejumJ 

Mail displays a message similar to the following one: 

%MAIL- I -CREATED, DISK: [THOMPSONJDEC_MEETINGS.TXT 

When you exit from Mail, the file is listed in your current directory (unless you 
specify another directory). If the file is a DDI F file, Mail preserves the OpenVMS 
RMS file tags and DDIF semantics (VMS Version 5.2-2 or later). 

The mail header is composed of the From:, To:, and Subj: lines. To create a file 
that does not include header information, specify the /N OF! EADER qualifier to 
the EXTRACT command. 

The following example shows how to create a file named J ANUARY_ 
MEETINGS.TXT containing the text of message number 3: 

MAIL> READ 3 fRitlLT| 


MAIL> EXTRACT/NOHEADER JANUARY_MEETINGS.TXT |Rjt5FFJ 

%MAIL- I -CREATED, DISKI : [JONES] JANUARY_MEE TINGS . TXT; 1 created 

MAIL> 

If the message has more than one header (for example, a forwarded message), 
only the topmost header is deleted. 

Use the /APPEND qualifier to the EXTRACT command to copy a message to the 
end of an existing file. Use the /ALL qualifier to copy all the files in the current 
folder to an existing file. 

6.4 Replying to a Message 

To reply to a message you have received, use the following procedure: 

1. Type REPLY at the MAI L> prompt and press Return. 

Mail displays the following header information: 

To: STONE: : THOMPSON 
Subj: RE: Budget Meeting 

Enter your message below. Press CTRL/Z when complete. CTRL/C to quit: 

2. Enter your message and press Ctrl/Z to send the message or press Ctrl/C to 
quit. 
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6.5 Forwarding a Message 

To forward a mail message to other users, enter the FORWARD command at the 
MAIL> prompt after you have read the message. Mail prompts you for the name 
of the addressee and a subject line, as follows: 

MAIL> FORWARD [r55FF] 

To: STONE:: JONES jRitUFF] 

Subj: FYI - Status of proposed budget meeting | Return | 

After you enter the requested information, press Return to send the message. 

If you forward a message that consists ofa .DDIF file, Mail sends the entire 
.DDIF file, including .DDI F semantics and the .DDI F tag, to the addressee. 

6.6 Organizing Your Messages 

To organize your mail messages, you can create your own mail files and folders. 

A mail file contains folders, and a folder contains mail messages. Each folder and 
file can contain any number of messages. 

Typically, you organize your messages by creating folders rather than by creating 
mail files. As with the default mail folders (NEWMAI L, MAI L, WASTEBASKET), 
the folders you create are normally stored in the mail file M Al L.MAI . The name 
of the current folder is displayed in the top right corner of the screen each time 
you enter a READ or DIRECTORY command. You can work only with messages 
that are in your current folder. 

If your mail file is very large (over 500 blocks), you might want to create separate 
mail files for the larger folders to improve Mail’s performance. 

6.6.1 Creating a Mail Subdirectory 

When you receive mail messages, they are by default written to files named 
MAI L$xxxxxxxxxx.MAI and are located in your top-level directory. (Note that the 
x's represent a long, random file specification.) Your default mail file, MAI L.MAI, 
is created in your top-level directory the first time you receive a mail message. To 
avoid the display of .MAI files in your top-level directory, use the Mail command 
SET MAI L_DI RECTORY. For example: 

MAIL> SET MAIL_DIRECTORY [.MAIL] [Return] 

This command creates a mail subdirectory and moves all your .MAI files to that 
subdirectory. To move the .MAI files from a subdirectory back to your top level 
directory, use the SET NOMAI L_DI RECTORY command. 

To display the name of the subdirectory that contains all your .MAI files, enter 
SHOW MAI L_DI RECTORY at the MAI L> prompt. 

MAIL> SHOW MAIL_DIRECTORY [RetunT[ 

Mail displays a message similar to the following: 

Your mail file directory is SY$L0GIN: [FRED .MAIL] 

6.6.2 Moving Messages into Folders 

You can use either the FILE command or the MOVE command to place the 
current message in a different folder. If the folder does not exist, Mail displays a 
message asking if you want to create it. After filing the message in the specified 
folder, Mail automatically deletes the message from the current folder. 
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6.6.3 Copying Messages Between Folders 

The Mail command COPY places a copy of the current message into the folder 
you specify. If the folder does not exist, Mail displays a message asking if you 
want to create it. 

The following commands copy all messages containing the word MEETING 
from the current folder to a folder named SCHEDULE. After the commands are 
executed, you have two copies of each message, one in the current folder and 
one in the folder SCHEDULE. The first command selects and displays the first 
message containing the word me&ing: 

MAIL> SEARCH MEETING [FtetlH 

MAIL> COPY SCHEDULE [Return] 

Folder SCHEDULE does not exist. 

Do you want to create it (Y/N, default is N) ?Y | Return | 

%MAIL-I-NEWFOLDER, folder SCHEDULE created 

This command selects and displays the next message containing meeting : 

MAIL> SEARCH [Return] 

MAIL> COPY SCHEDULE [Return] 

MAIL> SEARCH [Return] 

%MAIL-E-N0TF0UND, no messages containing 'MEETING' found 

6.6.4 Selecting Folders 

To display a list of the folders in your current mail file, enter the 
Dl RECTORY/FOLDER command, as shown in the following example: 

MAIL> DIRECTORY/FOLDER ]r5U17| 

Listing of folders in SYS$L0GIN: [FRED] MAIL. MAI; 1 
Press CTRL/C to cancel listing 
MAIL MEETING_MINUTES 

MEMOS PR0JECT_N0TES 

STAFF 

To select a new folder as your current folder, use one of the following commands: 

• SELECT foldername 

Selects the specified folder as the current folder. Subsequent Mail commands, 
such as READ and Dl RECTORY, use the selected folder. You do not need to 
specify a folder name with each command. 

• SET FOLDER foldername 

This command works the same as the SELECT command. 

• DIRECTORY foldername 

Selects the specified folder as the current folder and lists the messages in the 
folder. 

• READ foldername 

Selects the specified folder as the current folder and displays the specified 
message (by default, the first message in the folder). 
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6.6.5 Deleting Folders 

To delete a mail folder, delete all the messages in the folder or move them to 
another folder. For example, to delete the messages in the MUSIC folder, enter 
the following commands: 

MAIL> SELECT MUSIC ptetUFFI 
%MAIL-I-SELECTED, 2 messages selected 
MAIL> DELETE/ALL [Return] 

Note that after you have deleted all messages in a folder, when you select another 
folder, the empty folder is automatically deleted. 

6.6.6 Creating and Accessing Mail Files 

You can also create files to organize your mail messages. You use the same 
commands to create a mail file that you use to create a folder: COPY, MOVE, and 
FILE. After Mail prompts you for the name of the folder, it also prompts you for 
a file name. If you enter a new file name at the File: prompt, a new mail file is 
created. Figure 6-2 shows how typical users might organize their mail. 

Figure 6-2 Organization of a Typical Mail Directory 
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For example, to move the current message into a folder named FEED in the 
ACCOUNTS file, enter the following commands: 

MAIL> MOVE [Rejum] 

_Folder: FEED | Return | 

_File : ACCOUNTS [r5ST] 

The MOVE command creates the mail file ACCOUNTS. MAI , moves the current 
message into the FEED folder, and deletes the message from its current folder 
and file. 

To work within a mail file other than the default mail file, use the Mail command 
SET FILE to specify the alternate file. The Mail command SHOW FILE displays 
the name of the current mail file. For example: 

MAIL> SET FILE ACCOUNTS [rETT] 

MAIL> SET FOLDER FEED [Return] 

MAIL> SHOW FILE [rEEEEI 

Your current mail file is SYS$L0GIN: [FRED .MAI] ACCOUNTS .MAI; 1 . 

When you change mail files, the WASTEBASKET folder of the current mail file is 
emptied and deleted (if AUTO_PURGE is set) and the mail file is closed. 
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6.6.7 Correcting the Mail Message Count 

If the number of new (unread) mail messages displayed on your screen is 
inconsistent with the actual number of new messages, enter the READ/NEW 
command when there is no new mail. You will know there is no new mail when 
you enter the READ/NEW command and receive one of the following system 
messages: 

"%MAIL-W-NONEWMAIL, no new messages" 

"%MAIL-E-NOMOREMSG, no more messages" 

6.7 Deleting Messages 

To delete a mail message from the current folder, either enter the DELETE 
command while you are reading the message or enter the DELETE command 
followed by the number (or range of numbers) of the message you want to delete. 
You can use either the hyphen ( - ) or the colon ( : ) to define the range of messages 
to be deleted. For example, to delete messages 4, 5, 6, 11, 12, 14, 15, 16, and 17, 
enter the following at the MAI L> prompt and press Return: 

MAIL> DELETE 4-6,11,12,14:17 fRetum~| 

6.8 Recovering Deleted Messages 

When you delete a message, the message is moved to a folder called 
WASTEBASKET. Deleted messages collect in the WASTEBASKET folder until 
you exit from the current mail file (either by exiting from Mail or by specifying 
a different mail file). If you have issued the SET AUTO_PURGE command, 
when you exit from the current mail file, WASTEBASKET is emptied and the 
folder itself is deleted. During your interactive Mail session, you can recover any 
deleted message by moving the message out of the wastebasket folder. You can 
also empty the WASTEBASKET folder by entering the PURGE command. 

6.9 Printing Mail Messages 

To print a mail message, enter the PRINT command at the MAI L> prompt. When 
you exit from Mail or enter the command PRI NT/PRI NT, your message is sent 
to a queue for printing. By default, Mail sends your message to the SYS$PRI NT 
queue. To specify a different queue, use the PRI NT command qualifier /QUEUE. 
For example: 

MAIL> PRINT/QUEUE=AK34$PRINT |~Retum~| 

You can also select a different queue by issuing the SET QUEUE queue-name 
command. For example: 

MAIL> SET QUEUE AK34$PRINT [Return] 

This queue will remain your default print queue until you enter another SET 
QUEUE command, even if you exit Mail. 

Mail files are not sent to a print queue until you press Ctrl/Z, enter the EXIT 
command, or enter the PRI NT/PRI NT command. 
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6.10 Protecting Mail Files 

Mail files (for example, MAIL. MAI) are protected so that no one else can read 
them and so that you cannot accidentally delete them. The protection code that 
Mail gives .MAI files is: (S:RW,0:RW,G:,W:). The system (including Mail itself) 
and the owner (you) can read and write to the file. The group and world are 
denied all access. 

The Mail utility also has default file protection to discourage mail tampering. 
However, Mail is not completely tamperproof. Anyone with sufficient privileges 
can change protection and access mail files. These files are within your own 
directory, so you have the option of applying the file protection techniques 
for sensitive files described in Chapter 18. In addition, use your judgment 
in responding to mail requests. If a node is outside your local VMScluster 
environment, it is possible that the source node is incorrectly identified, either 
accidentally or intentionally. 

It is best to use discretion in the content of your mail messages and in the 
selection of your audience. Never reveal your password or send details about how 
to use your account. You have no control over information in a mail message once 
you have sent it. 

6.11 Customizing Your Mail Environment 

This section describes how you can use Mail more efficiently by performing the 
following tasks: 

• Using a text editor in Mail 

• Using the Mail keypad 

6.11.1 Using a Text Editor in Mail 

You can use a text editor to write a message before you send it. To do so, specify 
the /EDIT qualifier with the SEND command as shown in the following example: 

MAIL> SEND/EDIT [R5tUFE| 

After you respond to the To: and Subj: prompts, Mail i nvokes the text editor. 
Unless you have selected a different editor, Mail invokes the DECTPU-based EVE 
editor. 

Mail displays the following screen: 

[End of file] 


Buffer: MAIN | Write | Insert | Forward 

The [End of file] marker moves down as you enter text. For more information 
about the EVE editor, see Chapter 8. To send the message, press the Do key and 
enter the EXIT command. To cancel the send operation, press the Do key and 
enter the QUIT command. 


Note 

Do not edit a .DDI F mail file because you will no longer be able to use the 
file as a .DDI F file. If you edit a .DDI F mail file, you can access only the 
text of the file. 
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By specifying the /EDIT qualifier when you invoke Mail, you can use the editor 
for sending, replying, and forwarding during the ensuing mail session. You 
can also use keywords with the /EDIT qualifier to set the default for Mail. For 
example, to invoke the editor for every mail message you send or forward, specify 
the keywords SEND and FORWARD with the MAIL/EDIT command, as follows: 

$ MAIL/EDIT= (SEND, FORWARD) [Rejum] 

To invoke the editor only when you are replying to a message, use the keyword 
REPLY with the MAIL/EDIT command, as follows: 

$ MAIL/EDIT= (REPLY) [Return] 

To invoke the editor and display the message to which you are replying, use the 
REPLY keyword with the ^EXTRACT option, as follows: 

$ MAIL/EDIT= (REPLY=EXTRACT) [RitETH] 

If you do not specify a keyword with /EDIT, the default is /EDIT=(SEND, REPLY). 

To send or reply to a message, EXIT from the editor. To cancel a SEND or REPLY 
command, enter the QUIT command to exit from the editor. 

6.11.1.1 Selecting an Editor 

By default, Mail invokes the DECTPU-based EVE editor when you specify the 
Mail command SEND/EDIT. If you are not running an AN SI -compliant CRT 
(hard copy) terminal, you will not be able to invoke DECTPU-based editors (such 
as EVE and LSE). If you attempt to invoke a DECTPU-based editor, you will 
receive the error message : 

%TPU-E -NONANSI CRT, SYS$INPUT must be supported CRT 

By entering the Mail command SET EDITOR, you can specify that a different 
editor be invoked instead of EVE. For example, to select the EDT editor, issue 
the Mail command SET EDITOR EDT. The EDT editor remains your default Mail 
editor (even if you log out of the system and log back in) until you enter another 
SET EDITOR command. 

For example, to select the EDT editor, enter the following command at the MAIL> 
prompt: 

MAIL> SET EDITOR EDT [Return] 

In the following example, the default Mail editor has been set to EDT and the 
Mail command SEND/EDIT has been entered at the MAI L> prompt. 

MAIL> SEND/EDIT [RgtU?P| 

To: STONE: : THOMPSON [Return] 

Subj: Budget Meeting | Return | 

[EOB] 

~k 

You will see an asterisk (*) after you enter the subject line and press Return. 
Enter the CHANGE command and press Return to switch to the screen editor. 

For more information on using EDT, see Chapter 9. Enter the text of your 
message using EDT commands to move around in the buffer. A buffer is a 
temporary storage area that exists only during an editing session. To send the 
message, press Ctrl/Z. To cancel and not send the message, press Ctrl/C. 
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Displaying the Selected Editor 

To display the name of the selected Mail editor, enter the Mail command SHOW 
EDITOR. 

MAIL> SHOW EDITOR [r5M 

Mail displays the selected Mail editor as follows: 

Your editor is EDT. 

6.11.2 Using a Command File to Edit Mail 

You can define the logical name MAI L$EDIT to be a command file before entering 
Mail. Then, when you issue any Mail command that invokes an editor, the 
command file will be called to perform the edit. I n the command file, you can also 
invoke other utilities such as the spell -checker, and you can specify any function 
that can be done in a command file. Refer to Appendix C for an annotated 
example of a MAI LEDIT.COM command procedure and refer to Chapter 15 for 
more information on command files. 

If you wish to temporarily override your selected editor, you can define 
MAIL$EDIT to be the string "CALLABLE_" with the desired editor name 
appended. For example, to use callable EDT rather than callable EVE, you can 
type the following command: 

$ DEFINE MAIL$EDIT CALLABLE_EDT 

If you issue the SET EDITOR command during a session that was invoked with 
MAIL$EDIT defined, you override both your permanent selected editor and the 
current editor setting. In order to use the command file defined by MAIL$EDIT 
again, you must exit from Mail and restart it. 

6.11.3 Using the Mail Keypad 

You can use the numeric keypad on your keyboard to execute commands in Mail. 
Most keypad keys can execute two commands. To enter the top command for 
each key shown in Figure 6-3, press the appropriate key. To enter the bottom 
command shown in Figure 6-3, press the PF1 key first, and then the desired 
function key. 
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Figure 6-3 Mail Utility Keypad 
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For example, to execute the Mail command SEND, press KP7. To execute the 
Mail command SEND/EDIT, press the PF1 key first and then press KP 7. (For 
more information about Mail keypad commands, see Table 6-1.) 

6.11.3.1 Redefining Keypad Keys 

You can redefine the keypad keys to execute Mail commands when you are 
in Mail. Note that the previous definition of the key is superseded when you 
redefine a key. For example, to define the key KP2 as the Mail command 
PRI NT/PARAM=PAGE_ORI ENT ^LANDSCAPE, enter the following command 
line: 

MAIL> DEFINE/KEY KP2 "PRINT/PARAM=PAGE_ORIENT=LANDSCAPE" | Return! 

After you define KP2, you can press it to display the 
PRI NT/PARAM =PAGE_ORI ENT =LAN DSCAPE command. 

To increase the number of key definitions available on your terminal, use the 
/STATE qualifier. You can assign many definitions to the same key as long as 
each definition is associated with a different state. State names can be any 
alphanumeric string. By specifying states, you can press a key once to enter a 
command, and a second time to enter a qualifier. For example, to define PF1 
(pressed twice) as Dl RECTORY /FOLDER, do the following: 

1. Define the key PF1 to enter the Dl RECTORY command and to set the state 
to FOLDER. 

MAIL> DEFINE/KEY PF1 "DIRECTORY" /SET_STATE=FOLDER /NOTERMINATE |TtetU7FT 

2. Define the key PF1 to output the string "/FOLDER" when the state is set to 
FOLDER, as follows: 

MAIL> DEFINE/KEY PF1 "/FOLDER" / IF_STATE=FOLDER /TERMINATE |RitoT[ 
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3. Press PF1 twice to enter the command Dl RECTORY /FOLDER. 

The /TERMI NATE qualifier ends the command line so you do not need to 
press the Return key. 

Defining keypad keys in Mail is similar to defining keypad keys to execute DCL 
commands. For more information, see the description of the DEFINE/KEY 
command in the OpenVMS DCL Dictionary. 


6.11.3.2 Creating Permanent Key Definitions 

Any keypad keys that you define during a Mail session are lost when you exit 
from Mail. To retain keypad key definitions from one Mail session to another, 
create a file containing key definitions (for example, MAI L$KEYDEF.I Nl ) in your 
top-level directory. For example, the following MAI L$KEYDEF.I N I file contains 
six key definitions: 


DEFINE/KEY PF1 "DIRECTORY 
DEFINE/KEY PF1 "/FOLDER" 
DEFINE/KEY PF2 "SELECT " 
DEFINE/KEY PF2 "MAIL" 
DEFINE/KEY PERIOD "READ " 
DEFINE/KEY PERIOD "/NEW" 


/NOTERMINATE 

/TERMINATE 

/NOTERMINATE 

/TERMINATE 

/NOTERMINATE 

/TERMINATE 


/SET_STATE=f older 

/IF_STATE=f older 

/SET_STATE=mail 

/IF_STATE=mail 

/SET_STATE=new 

/IF_STATE=new 


To execute these commands each time you invoke Mail, enter the following 
command line in your login command file (LOGI N .COM ): 


S DEFINE MAILSINIT SYS$LOGIN:MAIL$KEYDEF . INI 


6.12 Summary of Mail Commands 

Table 6-1 lists all the Mail commands, grouped by function. For complete 
command descriptions, invoke Mail and enter the HELP command. 


Table 6-1 Summary of Mail Commands 


Command 

Qualifiers 1 

Reading Messages 

BACK 

Displays the message preceding the current or last-read message 
when the last command issued was READ. When the last 
command issued was DIRECTORY, the BACK command displays 
the preceding screen of the directory listing. 

/EDIT 

CURRENT 

Displays the beginning of the message you are currently reading. 

/EDIT 


1 For more detailed information, refer to online Help. 


(continued on next page) 


6-17 


Mail: Communicating with Other Users 
6.12 Summary of Mail Commands 


Table 6-1 (Cont.) Summary of Mail Commands 


Command 

Qualifiers 1 

Reading Messages 

DIRECTORY [folder-name] 

Displays a list of the messages in the current mail file, including 
message number, sender's name, date, and subject. 

/ BEFORE=date 

/CC SU BSTRI NG=text 

/EDIT 

/FROM SUBSTRING=t&ct 

/FOLDER 

/FULL 

/ [NOJMARKED 
/NEW 

/ [NOJREPLIED 

/SINCE =date 

/START =start-pdnt 

/SUBJ ECT SUBSTRING^t&ct 

/TO_SUBSTRING^text 

ERASE 

None 

Clears your terminal screen. 

EXTRACT 

/EDIT 

Places a copy of the current message into the specified output file. 
To copy a mail message to a folder in a Mail file, use either the 
COPY, FILE, or MOVE command. 


FIRST 

/EDIT 

Displays the first message in the current folder. 

LAST 

Displays the last message in the current folder. 

/EDIT 

NEXT 

/EDIT 

Skips to the next message and displays it. 

READ [folder-name] [message-number] 

Displays your messages. Pressing the Return key is the same as 
entering the READ command without parameters. 

/ BEFORE=date 
/CC SUBSTRING 
/EDIT 

/FROM SUBSTRI NG=t&(t 

/ [NOJMARKED 

/NEW 

/ [NOJREPLIED 
/SINCE=date 

/SUB] ECT SUBSTRING=text 
/TO_SUBSTRING^text 

SEARCH search-string 

None 

Searches the currently selected folder for the message containing 
the first occurrence of the specified text string. 


SHOW NEW MAIL COUNT 

None 

Displays the number of unread mail messages. 


Exchanging Messages 


1 For more detailed information, refer to online Help. 
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Table 6-1 (Cont.) Summary of Mail Commands 


Command 

Qualifiers 1 

Exchanging Messages 

ANSWER [filespec] 

REPLY [filespec] 

/ [NO]CC PROMPT (REPLY only) 
/[NO] EDIT 

Sends a message to the sender of the message you are currently 
reading or of the one you last read. 

/ EX / RAL 1 
/LAST 

/ [NOJPERSONAL NAME=name 
/[NOJSELF 

/ SUB] EOT =‘‘subject_text" 

FORWARD 

Sends a copy of the message you are currently reading (or have 
just read) to one or more users. 

/ [NO]CC PROMPT 
/[NO] EDIT 
/NOHEADER 

/ [NOJPERSONAL NAME=name 
/[NOJSELF 

/SUB] EOT ="subject-text" 

MAIL [filespec] 

SEND [filespec] 

Sends a message to one or more users. 

/ [NO]CC PROMPT 
/[NO] EDIT 
/NOHEADER 

/ [NOJPERSONAL NAME=name 
/[NOJSELF 

/SUB] EOT ="subject-text" 

Removing Messages 

DELETE [message-number] 

/ALL 

Deletes either the message you are currently reading, a range 
of messages, or the message you just read, and moves it to the 
WASTEBASKET folder. 


PURGE 

/RECLAIM 

Deletes all the messages in the WASTEBASKET folder. When you 
exit from Mail or enter a SET FILE command (to select a new 
mail file), an implicit purge is done to empty the WASTEBASKET 
folder, unless you have previously entered the SET NOAUTO_ 
PURGE command. 

/STATISTICS 

SET [NO]AUTO_PURGE 

None 

Determines whether Mail empties the WASTEBASKET folder 
when you enter the EXIT or SET FILE command. When you 
use the SET NOAUTO_PURGE command, you must enter the 
PURGE command periodically to delete the messages in the 
WASTEBASKET folder. 


SHOW AUTO_PURGE 

None 

Displays whether messages in the WASTEBASKET folder are 
deleted (purged automatically) when you enter the EXIT or SET 
FILE command. 


Printing Messages 


1 For more detailed information, refer to online Help. 
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Table 6-1 (Cont.) Summary of Mail Commands 


Command 

Qualifiers 1 

Printing Messages 

PRINT 

/ AFT E Retime 

Adds a copy of the message you are currently reading to the print 
queue. The files created by the PRINT command are released 
to the print queue when you exit from Mail. Multiple messages 
are concatenated into one print job unless you use the /NOW or 
/PRINT qualifier. 

/ALL 

/ [NO]BURST=keyword 

/CANCEL 

/ COPIES=n 

/ [NOJFEED 

/ [N 0]FLA G - keyword 

/ F ORM ^form-name 

/[NOJHOLD 

/ NAME =job-name 

/NOTIFY 

/NOW 

/ PARAMETERS=(parameter[,...]) 
/PRINT 

/ QUEUE - queue-name 
/ [NO]S PACE 
/ [NO]TRAI LER =keyword 

SET [NO]FORM form-name 

SHOW FORM 

None 

Sets the default print form for printing done within Mail. The 

SET NOFORM command clears the default print form. The 
SHOW FORM command displays the default print form. 


SET [NO]QUEUE queue-name 

SHOW QUEUE 

None 

Sets the default print queue to be used when you enter the 

PRINT command from within Mail. SET NOQUEUE clears the 
previously defined print queue and sets the queue to SYS$PRI NT, 
the default print queue. The SHOW QUEUE command displays 
your default print queue. 


Organizing Messages 

COPY folder-name [filename] 

Copies a message to another folder without deleting it from the 
current folder. If the specified folder does not exist, it is created. 

/ALL 

/ [NO]CONFIRM 

FILE folder-name [filename] 

MOVE folder-name [filename] 

/ALL 

/ [NOJCONFIRM 

Moves the current message to the specified folder and deletes the 
message from the original folder. 


SELECT [folder-name] 

SET FOLDER [folder-name] 

Establish a set of messages that you can affect as a group. 

You can copy or move this set of messages from one folder to 
another. You can also read and delete, or search and extract a 
set of messages. In addition, you can use the SELECT and SET 
FOLDER commands to move from one folder to another. 

/ BEFORE=date 
/CC SUBSTRING 
/FROM SUBSTRING 
/ [NOJMARKED 
/NEW 

/ [NO]REPLI ED 
/ S!NCE=date 

/SUB] ECT SUBSTRING^t&ct 
/TO SU BSTRI NG^text 


1 For more detailed information, refer to online Help. 
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Table 6-1 (Cont.) Summary of Mail Commands 


Command 

Qualifiers 1 

Organizing Messages 

SET FILE filename 

None 

Establishes (or opens) another file as the current mail file. 

By default, your mail file is MAI L. MAI . If you use the COPY 
command, the FILE command, or the MOVE command to create 
other mail files (for example, J OKES.MAI or HISTORY.MAI), you 
can then use the SET FILE command to open the Mail files. 


SHOW FILE 

None 

Displays the name of the mail file that is currently open. 

SHOW FOLDER [folder-name] 

Displays the current folder name. 

/BEFORE =date 

/CC SU BSTRI NG^text 

/FROM SUBSTRI NG^text 

/ [NO] MARKED 

/NEW 

/ [NO]RE PLIED 
/ SI NCE=date 

/SUBJECT SU BSTRI NG^text 
/TO_SUBSTRI NG^text 

SET WASTEBASKETNAME folder-name 

None 

Changes the name of the WASTEBASKET folder, which contains 
messages to be deleted. You can delete all the messages in the 
WASTEBASKET folder by entering the PU RGE command. If 
AUTO_PURGE is set, when you enter the EXIT command 
messages in the WASTEBASKET folder will be deleted. If 
AUTO_PURGE is set, you can avoid deleting messages in the 
WASTEBASKET folder by entering the QUIT command. 


SHOW WASTEBASKET NAME 

None 

Displays the name of the WASTEBASKET folder. 

SHOW DELETED 

None 

Displays the amount of deleted message space in the current mail 
file. 


Marking Messages 

MARK [message-number] 

/ALL 

Sets the current or specified message as marked. Marked 
messages are displayed with an asterisk (*) in the left-hand 
column of the directory listing. To select or organize marked 
messages, use the SELECT command with the /MARKED 
qualifier. 


UN MARK [message-number] 

/ALL 

Sets the current or specified message as unmarked. The asterisk 
(*) in the left-hand column of the directory listing is deleted. 


Customizing Mail 


1 For more detailed information, refer to online Help. 
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Table 6-1 (Cont.) Summary of Mail Commands 


Command 

Qualifiers 1 

Customizing Mail 

DEFINE/KEY key-name string 

Defines a key to execute a Mail command. You can press the 
defined key to enter a command instead of typing the command 
name. 

/ [NO]ECHO 

/ [NO]IF STATE =state list 
/[NO] LOCK STATE 
/ [NO]LOG 

/ [NOJSET STATE =state 
/ [NOJTERMINATE 

SHOW KEY [key-name] 

/ALL 

Displays the key definitions created by the DEFINE/KEY 
command. 

/BRIEF 
/DIRECTORY 
/ STATE =(state[,...]) 

EDIT [filename] 

Invokes your selected editor and enables you to edit a message 
before you send it. 

/COMMAND^ilespec 2 

/CREATE 2 

/ J OURNAL = filespec 2 

/OUTPUT =Tilespec 

/READ 2 

/RECOVER 2 

HELP [topic] 

None 

Displays information about Mail. To obtain information about 
individual commands or topics, enter HELP followed by the 
command or topic name. 


SET [NO]CC_PROMPT 

None 

Sets the default for determining whether the carbon copy (CC:) 
prompt appears when sending a message. 


SET COPY_SELF command[, command] 

None 

Sets the default for determining whether the SEND, REPLY, or 
FORWARD commands return to the sender a copy of the message 
bei ng sent. 


SHOW COPY_SELF 

None 

Displays which command (SEND, REPLY, or FORWARD) 
automatically sends a copy of the message to you. 


SET EDITOR editor-name 

None 

Selects the text editor to be used when you edit a message (for 
example, with the Mail command SEND/EDIT). You can use any 
callable editor available on your system. This command overrides 
any definition that the command procedure M Al L$E DIT has set. 


SHOW EDITOR 

None 

Displays the name of your selected text editor. 

SET [NO]FORWARD address 

Sets a forwarding address for your mail. 

None 

SHOW FORWARD 

/ALL 

Displays the name of your current forwarding address. 

/USER =user-name 

SET [NO]MAIL_DI RECTORY [ subdirectory-name] 

None 

Specifies that all mail files (file type .MAI) be moved from your 
SYS$LOGI N directory to the specified subdirectory. 



x For more detailed information, refer to online Help. 

2 This qualifier can be used only if you have issued the SET EDITOR EDT command. 


(continued on next page) 


6-22 


Mail: Communicating with Other Users 
6.12 Summary of Mail Commands 


Table 6-1 (Cont.) Summary of Mail Commands 


Command 

Qualifiers 1 

Customizing Mail 

SHOW MAI L_DI RECTORY 

/LOG 

Displays the name of the device and directory containing all your 
.MAI files. 


SET [NO]PERSONAL_NAME "text-string" 

None 

Appends a text string to the end of the From: field of mail 
messages you send. You can fill this field with your full name 
or any other information. Note that your personal name must 
begin with a letter and may not have two consecutive spaces. 


SHOW PERSONAL NAME 

/ALL 

Displays the text string established with the SET PERSONAL_ 
NAME command. 

/USER =user-name 

SHOW ALL 

None 

Displays detailed information about your current Mail settings. 


Exiting or Transferring Control 

ATTACH [process-name] 

/PARENT 

Permits you to switch control of your terminal from your current 
process to another process in your job. For example, while you 
are editing a file, you can use the SPAWN command to move to 
a subprocess (Mail) to read a new mail message. Then, you can 
enter ATTACFI to move back to the editing session. 


EXIT 

None 

Exits from Mail. When you enter the EXIT command, any 
messages in the WASTEBASKET folder are deleted unless you 
have issued the command SET NOAUTO_PURGE. You can also 
exit from Mail by pressing Ctrl/Z. 


QUIT 

None 

Exits from Mail without emptying the WASTEBASKET folder 
(deleted messages are not destroyed unless you enter the EXIT 
command or press Ctrl/Z). QUIT performs the same function as 
Ctrl/Y. 


SPAWN [command] 

Creates a subprocess of the current process. You can use the 
SPAWN command to leave Mail temporarily, perform other 
functions (such as displaying a directory listing or printing a 
file), and then return to Mail. 

/INPUT =filespec 
/ [NO] LOGICAL NAMES 
/ OUTPUT filespec 
/PROCESS =subprocess-name 
/ [NOJSYMBOLS 
/[NO] WAIT 

Compressing Mail Files 

COMPRESS [filespec] 

/ OUTPUT =out-filespec 

Makes an indexed mail file smaller. If you do not specify a file 
name, Mail compresses the mail file that is currently open. If 
there is no open mail file, Mail compresses the default mail file 
(MAIL. MAI). 


1 For more detailed information, refer to online FI elp. 

(continued on next page) 
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Table 6-1 (Cont.) Summary of Mail Commands 


Command 

System Management Commands 

Qualifiers 1 

REMOVE username 

Removes a user record from the system's mail profile, data file 
SYS$SYSTEM:VMSMAIL_PROFILE.DATA. Requires SYSPRV 
privileges. 

None 

SHOW FORWARD 

Displays the name of a user's current forwarding address. 

/USER = user-name 

SHOW PERSONAL NAME 

Displays the text string that a user has established with the SET 
PERSONAL_NAME command. 

/USER = user-name 

x For more detailed information, refer to online FI el p. 
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The OpenVMS Phone utility (PHONE) is a communication program designed to 
allow users to "talk" to each other via their terminals, computers, or computer 
networks. Phone (also sometimes referred to as the Phone facility) is designed 
to provide features similar to that of actual telephone communications, such as 
the hold button, conference calls, and telephone directories. You can use Phone 
to communicate with other users on your system or with any other system 
connected to your system by DECnet for OpenVMS networks. 

To invoke Phone, enter the PHONE command at the DCL prompt and press 
Return. You can specify the user name of the person with whom you want to 
communicate before or after you enter Phone. When you invoke the Phone utility, 
Phone takes control of your terminal and displays the Phone viewport as shown: 

Phone Viewport 

S PHONE 1 


OpenVMS Phone Facility ll-DEC-1994 


2 


TAURUS 

: : SMITH 

3 

GEMINI: 

: PETERS 

4 


The fields on the viewport are: 

1 The command that is used to enter the Phone utility. 

2 The Phone prompt, also known as the switchhook. This is where you enter 
Phone commands. You can get to the Phone command line by pressing 
the switchhook (%) character at any time during your conversation. The 
switchhook character is the percent sign (%) on your keyboard. 

3 The top part of the viewport is where the conversation text that you type 
appears. 

4 The lower part of the viewport is where the conversation text that other 
participants type appears. You can have up to six participants in a phone 
conversation. 
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You can obtain information about Phone by invoking the HELP command at the 
DCL prompt as follows: 

$ HELP 

Topic? PHONE 

You can also enter Help from within the Phone utility by entering the HELP 
command at the switchhook (%) prompt. 

7.1 Screen Layout 

Each person engaged in the conversation has a viewport on the screen. Phone 
can display as many as six viewports at a time. 

The viewport contains information regarding the user's name, the text of the 
conversation, and various status indicators, such as who is on hold. User names 
of people that you have on hold can be temporarily eliminated from the screen to 
make room for new participants. 

7.2 Entering Phone Commands 

To enter Phone commands, you must first press the switchhook character (%). If 
you are using the Phone utility but are not currently engaged in a conversation, 
the switchhook character is optional because there is no ambiguity between a 
command and conversation. 

You can press Ctrl/W at any time during your current conversation to refresh the 
screen. 

The DIAL, DIRECTORY, MAIL, and PHONE commands accept logical names. To 
prevent Phone from treating a parameter to these commands as a logical name, 
prefix the parameter with an underscore. 

7.3 Conversation Text 

When you are engaged in a conversation, most of the characters that you type 
are considered part of that conversation and are sent to each participant. The 
exception is the percent sign (%), which signals that you want to enter a 
Phone utility command. You can enter any Phone utility command during a 
conversation. See Section 7.5 for a list of available Phone commands. 

7.4 Customizing Your Phone Viewport 

When entering the DCL command PHONE, you can supply the following 
qualifiers that modify the characteristics of the simulated telephone: 

/SCROLL Determines how new lines of text are displayed on the screen 

when the viewport becomes full. 

/SWITCH_HOOK Specifies the character to be used for the switchhook prompt. 

The switchhook character must be must be entered before each 
Phone utility command that is entered during a conversation. 

/VI EWPORT_SIZE Specifies the maximum number of lines in a viewport, including 

the heading line and the bottom line of dashes. 

For complete descriptions of Phone qualifiers, enter HELP PHONE at the DCL 
prompt. 
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7.5 Summary of Phone Commands 

Table 7-1 summarizes all of the Phone commands available. There are no 
qualifiers associated with the commands in this table. 


Table 7-1 Summary of Phone Commands 


Command 

Description 

ANSWER 

Answers the phone when you receive a call. 

DIAL 

Places a call to another user. 

DIRECTORY 

Displays a list of those users with whom you can talk on your 
system or on any other system in the network. 

EXIT 

Exits from the Phone utility. 

FACSIMILE 

Allows you to include the contents of a file in your conversation. 

HANGUP 

Hangs up your phone. This disconnects all current links— the 
current conversation, anyone you have on hold, and anyone who has 
you on hold. 

HELP 

Enables you to obtain online information about the Phone utility. 

HOLD 

Enables you to put on hold other users who are currently 
participating in a conversation with you. 

MAIL 

Allows you to send a brief message to another person. 

PHONE 

Is synonymous with the DIAL command. 

REJ ECT 

Allows you to reject a call from another user while you are using 
Phone. 

UNHOLD 

Reverses the most recently entered HOLD command. 


For complete descriptions of Phone commands, invoke Phone and enter the HELP 
command. 
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The Extensible Versatile Editor (EVE) is a general-purpose text editor based on 
the DEC Text Processing Utility (DECTPU). DECTPU is a high-performance, 
programmable text processor. Using EVE, you can create and edit text files such 
as business letters, technical documents, and program source files. 

EVE is the default editor on the OpenVMS operating system. Unless you define a 
different default editor, EVE is invoked when you enter the EDIT command. 

You can use EVE on a character-cell terminal (VT100, VT200, VT300, or VT400 
series) or on a workstation with the OpenVMS DECwindows Motif user interface. 

This chapter provides the following: 

• An introduction to EVE, including specific EVE features 

• An overview of how to get help at any time during your EVE editing session 

• Tutorials that lead you step-by-step through EVE editing tasks 

• Advanced EVE editing techniques 

8.1 EVE Features 

Using EVE, you can do the following: 

• Create and edit text files such as letters, reports, program sources, and other 
documents. 

• Perform text formatting operations, such as erase, cut, paste, fill, find, 
replace, and paginate. 

• Use multiple buffers and windows to view and edit different files in the same 
editing session. 

• Define keys for editing operations, including learn sequences (to bind several 
commands or keystrokes to a single key) and setting the EDT keypad or 
WPS-PLUS keypad. 

• Select text in boxes or in linear ranges for cut-and-paste or other edits. 

• Use wildcards to search for patterns of text. 

• Execute DCL commands (such as DIRECTORY) from within the editor. 

• Run DECspell to check a selection or an entire buffer. 

• Spawn subprocesses or attach to other processes. 

• Compile and execute DECTPU procedures to extend EVE. 

• Add to or delete menu items from the DECwindows interface. 
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• Save compiled procedures, menu definitions, key definitions, and other 
customizations for future sessions. (See Appendix A for more information on 
customizing EVE.) 

• Use initialization files at startup or during an editing session. 

• Recover your work by using keystroke or buffer-change journaling when a 
system failure interrupts your editing session. 

• Get comprehensive online help on EVE commands, keys, menu items, and 
other topics, including DECTPU built-in procedures. 

8.2 Getting Help 

You can get online help at any time during your editing session. There are two 
kinds of online help available with the EVE editor: 

• Keypad help, which you access with the Help key on your terminal 

• EVE help, which you access with the HELP command at the EVE command 
prompt 

8.2.1 Using Keypad Help 

To access keypad help, follow these steps: 

1. Press the Help key. 

The Help utility displays a diagram of your keypad. 

2. Follow the directions on the screen to get information on: 

• EVE commands 

To get help on EVE commands, enter a command name or a question 
mark ( ? ) and press the Return key. 

• Defined keys 

To get help on a key that you have defined, press that key, or use the 
SHOW KEY command. 

• Listing of key definitions 

To list all key definitions, type the word keys and press the Return key, 
or press GOLD HELP. The GOLD key is the PF1 key on the numeric 
keypad. 

• To exit from Help, press the Return key. 

8.2.2 Using EVE Help 

To use the HELP command to access EVE Help, follow these steps: 

1. Press the Do key. 

2. Enter the command H ELP. 

Use the Prev Screen and Next Screen keys to scroll through the list of 
available help topics. 

3. To exit from Help, press the Return key. 

To get information about a particular command, enter HELP followed by the 
command name and press the Return key. The help text appears on the screen. 
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For example, to get help on the MOVE BY LINE command, enter the command 
HELP MOVE BY LINE. The help text in Example 8-1 appears on your screen. 

Example 8-1 Sample Help Text 

MOVE BY LINE 

Moves the cursor a line at a time in the current direction. 

Keys: EVE Default VT100 Keypad 

F12 MINUS on keypad 

Steps : 

1. If necessary, set the direction to move in — forward or reverse. 

2. Use MOVE BY LINE (see key list above). 

Usage notes: 

o In forward direction, moves to the end of the current line, or to the 
end of the next line, if any. 

o In reverse direction, moves to the start of the current line, or to 
the start of the next line, if any. 

Related topics: 

CHANGE DIRECTION END OF LINE LINE START OF LINE 

You can also get help on DECTPU built-in procedures by entering the command 
HELP TPU . 

For information on abbreviating commands, see the online help topic called 
Abbreviating. 

8.3 Beginning an Editing Session 

To invoke EVE, use the EDIT/TPU command. When you begin an editing session, 
you can specify the name of an existing file or a new file you want to create. If 
you do not specify a file name now, EVE prompts you for a file name when you 
end your editing session if you added text to the default buffer called Main. 

The following example invokes EVE to create a new file named NEWFI LE.DAT: 

$ EDIT/TPU NEWFILE.DAT 

This command produces the screen that appears in Figure 8-1. 

Figure 8-1 EVE Sample Screen Layout 

[End of file] 


Buffer: NEWFILE.DAT 


Write | Insert | Forward 
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The sample screen contains the following areas: 

• A buffer is a temporary holding area into which EVE inserts the text of the 
file you are editing. 

• A window is an area of your screen that displays a buffer. EVE buffers exist 
only during the editing session. When you end an editing session, you can 
save your edits or discard them. 

• The end-of-file marker marks the end of an EVE buffer. It is visible only on 
the screen and does not become part of your file. When you add text to the 
buffer, the end-of-file marker moves down. Depending on the length of your 
terminal screen, the marker may not be visible when you view the beginning 
of a buffer that contains many lines of text. 

• A highlighted status line appears at the bottom of the EVE window and 
provides information about the buffer you are viewing in the window. The 
status line shows the buffer name, editing status (write or read-only), current 
mode (insert or overstrike), and current direction (forward or reverse). 

• You use the command line to enter line-mode commands (see Section 8.4). 
You get the command line by pressing the Do key. 

• The message window contains an informational message that appears 
beneath the highlighted status line when you invoke EVE and specify a file 
name on the command line. The message states either that the file is a new 
file or that a certain number of lines were read from an existing file. During 
the editing session, EVE displays other messages in the message window. 

8.4 Entering Commands 

There are two ways to enter EVE commands: 

• Type in commands on the command line interface (see Section 8.4.1). 

• Use defined keys on either the EDT or WPS keypad (see Section 8.4.2). 

8.4.1 Using Typed Commands 

To type a command, take these steps: 

1. Press the Do key. 

The cursor moves to the command window and EVE prompts you to type a 
command. 

2. Type a command. You can abbreviate the command by using the first 
few letters of the command. EVE is not case sensitive. You can use any 
combination of uppercase and lowercase characters in the command line 
except when specifying strings for the FIND and REPLACE commands. 

3. Press the Do key or the Return key. 

EVE executes the command or prompts you for further information. 

For a complete list of EVE commands, see the online help in EVE or the 

Extensible Versatile Editor Reference M anual . 
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8.4.2 Using Defined Keys 

You can use defined keys to enter EVE commands. Each defined key performs one 
editing command. You can also define your own keys to perform EVE functions 
(see Section A. 2). 

EVE defines some keys by default. The predefined keys on VT200, VT300, and 
VT400 series terminals include: 

• The minikeypad (located between the main keyboard keys and the numeric 
keypad, above the arrow keys) 

• Certain function keys 

• Certain control key sequences 

Figure 8-2 shows the predefined keys for the VT200, VT300, and VT400 series 
terminal. On VT100 series terminals, EVE automatically defines most of the 
numeric keypad keys, the four arrow keys, and certain control keys. Figure 8-3 
shows the predefined keys for the VT100 series terminal. 

Control keys, arrow keys, and the Tab, Return, and Delete keys have the same 
definitions on all three types of terminal. 


Figure 8-2 EVE Keys — VT200 Series, VT300 Series, and VT400 Series Terminals 


EVE Default Keys (SET KEYPAD NUMERIC) 
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Change 

Direction 

Line 

Word 

Mode 
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Help 

Keypad 
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<X] Delete 
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Enter Return 

PF4 Do 
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Ctrl/B RECALL 
Ctrl/E END OF LINE 
Ctrl/H START OF LINE 
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Ctrl/L INSERT PAGE BREAK 
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GOLD key functions are shown in gray shading. 
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Figure 8-3 EVE Keys — VT100 Series Terminals 
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8.5 Saving Your Edits and Exiting from EVE 

You can use one of three methods to save your edits and to exit from EVE : 

• WRITE FILE command 

Saves a file without terminating your editing session 

• EXIT command 

Terminates your editing session and saves the changes to your file 

• QUIT command 

Terminates your editing session without saving changes to your file 

8.5.1 Using the WRITE FILE Command 

To save the text in your buffer by writing it to a file without exiting from EVE, 
use the WRITE FILE command. If no file is associated with your buffer, EVE 
prompts for a file name, as follows: 

Type filename for buffer Main (press RETURN to not write it) : 

Type the name of the file and press the Return key to write out the buffer to a 
file. 

8.5.2 Using the EXIT Command 

To save your edited text, use the EXIT command. You can enter the EXIT 
command by pressing the F10 key (on VT200, VT300, or VT400 series terminals) 
or by pressing Ctrl/Z. 

If you have modified the current buffer, EVE creates a new version of the file with 
the same file name and file type as the original version, with the version number 
incremented by 1. For example, if you use the EXIT command after modifying a 
file named FUN.DAT;!, the output file is named FUN.DAT;2. 
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8.5.3 Using the QUIT Command 

To end a session without saving your edits, enter the QUIT command. For 
example, if you have modified a buffer named FUN. DAT and enter the QUIT 
command, the following display appears on your terminal screen: 

Command: QUIT 

Buffer modifications will not be saved, continue quitting (Y or N) ? 

Type Y and press the Return key if you want to quit without saving the edits. If 
you change your mind and decide to save your edits, type N, press the Return 
key, and use the EXIT command to exit from the buffer. 

If you have modified buffers other than the current one, EVE asks if you want to 
save the contents of the other buffers. If you type Y, EVE creates a new version 
of an existing file, incrementing the version number by 1. EVE prompts for a file 
name if no file currently exists. 

If no buffers have been modified, then EXIT and QUIT are the same. For 
example, if you use EVE to inspect a file without making edits, you can quit by 
pressing Ctrl/Z. 

8.6 Editing Text 

Once you know how to invoke EVE and how to enter commands, you can use 
EVE commands to create and edit files. Using editing keys and commands, you 
can move the cursor, set buffer mode, and perform editing operations such as 
entering, erasing, restoring, and moving text. 

As a convention, EVE shows key names (with the SFIOW KEY or FIELP KEYS 
command) by using a slash for control keys, shifted function keys, and Alt 
key combinations, and a space or a dash for GOLD key sequences. Thus, key 
combinations that require you to hold down one key (such as Ctrl) while pressing 
another key are shown with a slash; key combinations in which you press one 
key after another (such as GOLD-Help) are shown with a space or a dash. 

For instructions to define key sequences and redefine the GOLD key, refer to 
Appendix A. 

8.6.1 Moving the Cursor 

When editing files with EVE, you move the cursor where you want to perform 
an editing function. The more quickly and efficiently you move the cursor 
through the text, the more time you save in your editing session. You can use the 
keyboard or commands to move the cursor. 

Table 8-1 shows EVE editing keys that move the cursor. For more information 
about the GOLD key combinations listed, see the online help topic GOLD. 
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Table 8-1 EVE Editing Keys That Move the Cursor 


Key or Key Sequence 

Function 

T 

Same as MOVE UP. Moves the cursor up one line. On 
VT100 series terminals, KP5 is also defined as MOVE U P. 

l 

Same as MOVE DOWN. Moves the cursor down one line. 

On VT100 series terminals, KP2 is also defined as MOVE 
DOWN. 

Same as MOVE LEFT. Moves the cursor one character or 
column to the left. On VT100 series terminals, KPlisalso 
defined as MOVE LEFT. 

— > 

Same as MOVE RIGHT. Moves the cursor one character 
or column to the right. On VT100 series terminals, KP3 is 
also defined as MOVE RIGHT. 

Ctrl/E 

or GOLD -»• 

Same as EN D OF LINE. Moves the cursor to the end of the 
current line. 

Ctrl/H 
or GOLD <- 

Same as START OF LINE. Moves the cursor to the 
beginning of the current line. 

GOLD t 

Same as TOP. Moves the cursor to the top of the current 
buffer. 

GOLD | 

Same as BOTTOM. Moves the cursor to the bottom of the 
current buffer. 

GOLD Next Screen 

Same as NEXT WINDOW. Moves the cursor to the last 
position the cursor occupied in the next window on your 
screen, if you are using two or more windows. 

GOLD Prev Screen 

Same as PREVIOUS Wl NDOW. Moves the cursor to the 
last position the cursor occupied in the previous window on 
your screen, if you are using two or more windows. 


Table 8-2 shows EVE commands that move the cursor. 

Table 8-2 EVE Commands That Move the Cursor 


Command 

Function 

BOTTOM 

Moves the cursor to the end of the current buffer. By default, 
EVE defines GOLD | as BOTTOM. 

CHANGE DIRECTION 

Changes the direction of the current buffer. The direction of 
the buffer is shown in the status line. 

END OF LINE 

Moves the cursor to the end of the current line. By default, 
EVE defines both Ctrl/E and GOLD —> as END OF LINE. 

FORWARD 

Default setting. Sets the direction of the current buffer to 
forward; that is, to the right and down. The direction of the 
buffer is shown in the status line. 

GOTO 

Moves the cursor to the position you specify, as previously 
labeled with the MARK command. 

LINE 

Moves the cursor to the beginning of a line (specified by the 
line number). 

MARK 

Puts an invisible marker at the current position and associates 
it with the name you specify. Later, using the GO TO 
command, you can return to the marked position. 

(continued on next page) 
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Table 8-2 (Cont.) EVE Commands That Move the Cursor 


Command 

Function 

MOVE BY LINE 

1 n forward direction: moves the cursor to the end of the 
current line or, if the cursor is already at the end of a line, to 
the end of the next line. 1 n reverse direction: moves the cursor 
to the beginning of the current line or, if the cursor is already 
at the beginning of a line, to the beginning of the previous line. 
On VT200, VT300, and VT400 series terminals, EVE defines 
the F12 key as MOVE BY LINE. On VT100 series terminals 
EVE defines the Minus key on the keypad as MOVE BY LINE. 

MOVE BY PAGE 

Moves the cursor to the next or previous page break (form 
feed), depending on the current direction. If there is no page 
break in the current direction, the cursor moves to the bottom 
or top of the buffer. 

MOVE BY WORD 

1 n forward direction: moves the cursor to the beginning of the 
next word or, if the cursor is already at the end of a line, to 
the beginning of the next line. 1 n reverse direction: moves the 
cursor to the beginning of the previous word or, if the cursor 
is already at the beginning of a line, to the end of the previous 
line. 

NEXT SCREEN 

Scrolls forward in the current buffer by the number of lines 
in the current window minus one. For example, if the current 
window is 12 lines long, the NEXT SCREEN command scrolls 
the cursor forward 11 lines. On VT200, VT300, and VT400 
series terminals, EVE defines the E6 key (Next Screen) as 
NEXT SCREEN. On VT100 series terminals, EVE defines the 
KPO key on the keypad as NEXT SCREEN. 

NEXT WINDOW or 
OTHER WINDOW 

Moves the cursor to the next window on your screen, if there is 
one. The cursor appears in the last location it occupied in that 
window. EVE defines GOLD Next Screen as NEXT WINDOW. 

PREVIOUS SCREEN 

Scrolls backward in the current buffer by the number of lines 
in the current window minus one. For example, if the current 
window is 12 lines long, the PREVIOUS SCREEN command 
scrolls the cursor backward 11 lines. On VT200, VT300, and 
VT400 series terminals, EVE defines the E5 key (Prev Screen) 
as PREVIOUS SCREEN. On VT100 series terminals, EVE 
defines the Period key on the keypad as PREVIOUS SCREEN. 

PREVIOUS WINDOW 

Moves the cursor to the previous window on your screen, 
if there is one. The cursor appears in the last location it 
occupied in that window. EVE defines GOLD Prev Screen as 
PREVIOUS WINDOW. 

REVERSE 

Sets the direction of the current buffer to reverse; that is, to 
the left and up. The direction of the buffer is shown in the 
status line. 

SET CURSOR BOUND 

Makes the cursor follow the flow of text. The cursor cannot 
move into an unused portion of the buffer. Similar to cursor 
behavior in EDT, WPS, and other editors. 

SET CURSOR FREE 

Default setting. You can move the cursor anywhere in the 
buffer and enter text there. 

(continued on next page) 
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Table 8-2 (Cont.) EVE Commands That Move the Cursor 


Command 

Function 

SET SCROLL 
MARGINS 

Sets the top and bottom distances at which scrolling begins 
automatically as you move the cursor up and down. You 
specify these distances as numbers of lines or as a percentage 
of the window size. The default setting is 0; that is, scrolling 
starts when you move past the top or the bottom of the wi ndow. 

SHIFT LEFT 

Shifts the current EVE window to the left by the number of 
columns you specify. With SHIFT RIGHT and SHIFT LEFT 
commands, you can view the undisplayed portion of long lines 
of text without having to change the width of the window or 
use 132-column mode. The SHI FT LEFT command shifts the 
window only if you have used the SH 1 FT RIGHT command. 

SHIFT RIGHT 

Shifts the current EVE window to the right by the number of 
columns you specify. With SHIFT RIGHT and SHIFT LEFT 
commands, you can view the undisplayed portion of long lines 
of text without having to change the width of the window. 

START OF LINE 

Moves the cursor to the beginning of the current line. By 
default, EVE defines both Ctrl/H and GOLD <- as START OF 
LINE. 

TOP 

Moves the cursor to the beginning of the current buffer (upper 
left corner). By default, EVE defines GOLD f as TOP. 


Use the following example to move the cursor through a buffer: 

1. Invoke EVE and create the buffer SCHEDULE.DAT with the following 
command: 

$ EDIT/TPU SCHEDULE.DAT 

EVE puts the cursor at the top of the buffer and waits for you to enter text. 

2. Enter the following text. 

Schedule for 1 July 
10:00 AM meeting with supervisor 
Read and review memo from Sally 
Work on Pascal program 

The [End of file] marker moves down in the buffer as you enter text and the 
the cursor is positioned at the end of the text you inserted. 

3. Enter the TOP command to move the cursor to the beginning of the file. 

4. Press Ctrl/E to move the cursor to the end of the first line of text. Ctrl/E 
works the same way in EVE as it does in DCL. 

5. Enter the BOTTOM command to move the cursor to the end of the buffer. 

6. Press the up arrow key to move the cursor up one line to the fourth line of 
text. 

7. Press the Change Direction key to change the current buffer direction to 
reverse. 

8. Press the Move by Line key to move the cursor to the beginning of the third 
line of text. 

9. Enter the command LINE 1 to move the cursor to the beginning of the first 
line of the buffer. 
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10. To exit from EVE, press Ctrl/Z. 

8.6.2 Entering Text 

You can enter keyboard characters, entire files, and special nonprinting characters 
(such as control characters) into the buffer you are currently editing. You can use 
the keypad or commands to enter text. 

Table 8-3 shows the EVE editing keys that you can use to enter text. 


Table 8-3 EVE Editing Keys for Entering Text 


Key or Key 
Sequence 

Function 

Ctrl/A 

Same as the CHANGE MODE command. Changes the editing mode 
for the current buffer as shown in the highlighted status line. In insert 
mode, EVE inserts text at the character position, moving existing text 
to accommodate the insertion. 1 n overstrike mode, EVE overwrites text 
at the current position. On VT200, VT300, and VT400 series terminals, 
EVE defines the F14 key as CHANGE MODE. On VT100 series 
terminals, EVE defines the Enter key on the keypad as CHANGE 
MODE. 

Ctrl/V 

Same as the QUOTE command. You can insert nonprinting characters 
or control codes. To search for special characters, first press the Find 
key, then press Ctrl/V and the special character to be found. Activate 
the search by pressing the Return key. 

Table 8-4 shows the commands that you can use to enter text. 

Table 8-4 EVE Commands for Entering Text 

Command 

Function 

CHANGE 

MODE 

Same as Ctrl/A. Changes the current editing mode as shown in the 
highlighted status line. In insert mode, EVE inserts text at the 
current position, moving existing text to accommodate the insertion. 

In overstrike mode, EVE overwrites text at the current position. On 
VT200, VT300, and VT400 series terminals, EVE defines the F14 key 
as CHANGE MODE. On VT100 series terminals, EVE defines the 

E nter key on the keypad as CHANGE MODE. 

INCLUDE FILE 

1 nserts the contents of the specified file into the current buffer at the 
line above the cursor position. This is useful for combining files. 

INSERT MODE 

Sets the mode of the current buffer to insert, as opposed to overstrike. 
In insert mode, EVE inserts text at the current position, moving 
existing text to accommodate the insertion. 

OVERSTRIKE 

MODE 

Sets the mode of the current buffer to overstrike, as opposed to insert. 

1 n overstrike mode, EVE overwrites text at the current position. 

QUOTE 

Same as Ctrl/V. Enters a nonprinting character or a control code 
that you specify by pressing a key. You can quote a control code or 
other character when you enter a string for the FIND or REPLACE 
commands. For example, you can quote the Tab key to search for tab 
characters. 


You can add text to your buffer in the following ways: 
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• Text 

You can type characters at the keyboard. EVE adds the characters to the 
buffer at the current cursor position according to the current mode of the 
buffer (insert or overstrike). 

• Files 

You can add an entire file by pressing the Do key and entering the EVE 
command I NCLUDE FILE. Type the file specification at the File to include: 
prompt and press the Return key. Regardless of the current mode (insert or 
overstrike) of the buffer, EVE inserts the entire contents of the specified file 
into the buffer just before the line where the cursor currently appears. 

You can use wildcards in the file specification. If there is more than one 
match for a file specification with a wildcard, EVE displays a list of choices 
and prompts you to provide a more complete file specification. If the specified 
file does not exist, EVE displays a message stating that it could not include 
the file. 

• Special nonprinting characters 

You can use the QUOTE command to add special nonprinting characters by 
pressing Ctrl/V followed by the special character. For example, to insert an 
escape character into the buffer, press Ctrl/V followed by Ctrl/[. The special 
character is added according to the current mode of the buffer (insert or 
overstrike). 

8.6.3 Setting Buffer Mode 

Before you begin typing text, check whether your buffer is in insert mode or 
overstrike mode. 

To determine the mode your buffer is in, look at the highlighted status line. If 
the buffer is in insert mode, text is inserted at the cursor position, and text that 
already appears in the buffer moves to accommodate your insertions. If the buffer 
is in overstrike mode, text that you type at the keyboard is inserted at the cursor 
position, and the text that already appears in the buffer is overwritten as the 
cursor moves through it. 

To change from one mode to another, press Ctrl/A. 

Use the following example to add text to a file in both insert mode and overstrike 
mode: 

1. lnvokeEVEtoedittheexistingfileSCFIEDULE.DAT (see Section 8.6). 

2. Check the highlighted status line to ensure that EVE is in insert mode. 

3. If EVE is in overstrike mode, press Ctrl/A to change to insert mode. 

4. M ove the cursor to the first letter s in the word supervisor, type Engineering, 
and press the space bar. 

The word Engineering is inserted in your text buffer, and the rest of the text 
on the line moves to the right. 

Schedule for 1 July 

10:00 AM meeting with Engineering supervisor 
Read and review memo from Sally 
Work on Pascal program 
[End of file] 

Buffer: SCHEDULE.DAT | Write | Insert | Forward 
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5. Press Ctrl/A to change to overstrike mode. 

6. Move the cursor to the letter S in the word Sally and type Peggy. 

The word Peggy is placed in the buffer, overwriting the word Sally. 

Schedule for 1 July 

10:00 AM meeting with Engineering supervisor 
Read and review memo from Peggy 
Work on Pascal program 
[End of file] 

Buffer: SCHEDULE.DAT | Write | Overstrike | Forward 

7. To exit from EVE, press Ctrl/Z. 

8.7 Erasing and Restoring Text 

With EVE, you can easily erase text or correct mistakes made during an editing 
session. If you erase text by mistake, you can restore the most recently erased 
text to its former location or, by moving the cursor, to another location. Table 8-5 
shows EVE editing keys that erase and restore text. 


Table 8-5 EVE Editing Keys for Erasing and Restoring Text 


Key or Key Sequence 

Function 

Delete key or Delete 

Erases the character to the left of the cursor. Same as 
the DELETE command. If pending delete is enabled, 
DELETE erases text in the select range and puts it 
into the Restore Selection buffer. For more information 
about using pending delete, see Section 8.7.1. 

Ctrl/J 

Same as ERASE WORD. Erases the current word or, 
if the cursor is between words, erases the next word. 
On VT200, VT300, and VT400 series terminals, EVE 
defines the F13 key as ERASE WORD. On VT100 
series terminals, EVE defines the Comma key on the 
keypad as ERASE WORD. 

Ctrl/U 

Same as ERASE START OF LINE. Erases characters 
left of the cursor to the start of the line. 

GOLD 1 nsert Here 

Same as RESTORE. Reinserts, at the current position, 
the word, line, or sentence that you just erased with 
an EVE command or editing key. 

GOLD F13 

Same as RESTORE WORD (except with the WPS 
keypad). Reinserts, at the current position, the word 
that you last erased. 


To erase text from your buffer, move the cursor to the text you want to erase and 
press the appropriate editing key or enter the appropriate EVE command. 

Table 8-6 shows EVE commands that erase and restore text. 
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Table 8-6 EVE Commands for Erasing and Restoring Text 


Command 

Function 

DELETE 

Erases the character to the left of the cursor. 1 n insert 
mode, EVE moves existing text to accommodate the 
deleted character. In overstrike mode, EVE replaces 
the character with a space. At the start of a line, 
DELETE erases the carriage return for the previous 
line (regardless of mode) and the current line moves 
up. If pending delete is enabled, DELETE erases 
text in the select range and puts it into the Restore 
Selection buffer. For more information about using 
pending delete, see Section 8.7.1. 

ERASE CHARACTER 

Erases the character the cursor is on. 1 n insert mode, 
EVE moves existing text to accommodate the deleted 
character. In overstrike mode, EVE replaces the 
character with a space. If the cursor is at the end of 
the line, the carriage return is erased— regardless of 
the mode— and the next line moves up. 

ERASE LINE 

E rases from the current character to the end of the 
line, appending the next line to the end of the current 
line. If the cursor is at the end of the line, only the 
carriage return is erased and the next line moves up. 

ERASE PREVIOUS WORD 

Erases the previous word or the word the cursor is on. 

1 f the cursor is between words or on the first character 
of a word, the previous word is erased. If the cursor 
is in the middle of a word, all of that word is erased 
(same as ERASE WORD). If the cursor is at the start 
of a line, the carriage return at the end of the previous 
line is erased and the current line moves up. 

ERASE START OF LINE 

Erases the current line of text, starting with the 
character left of the cursor until the start of the line. 

If you are already at the start of a line, nothing is 
erased. 

ERASE WORD 

Erases the current word or, if the cursor is between 
words, erases the next word. Same as Ctrl/J . On 
VT200, VT300, and VT400 series terminals, EVE 
defines the F13 key as ERASE WORD. On VT100 
series terminals, EVE defines the Comma key on the 
keypad as ERASE WORD. If the cursor is at the end 
of the line, only the carriage return is erased and the 
next line moves up. 

RESTORE 

Reinserts, at the current position, the word, line, or 
sentence that you last erased with an EVE command 
or editing key. RESTORE does not restore single 
characters. EVE defines GOLD Insert Here as 
RESTORE. 

(continued on next page) 
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Table 8-6 (Cont.) EVE Commands for Erasing and Restoring Text 


Command 


Function 


RESTORE CHARACTER 


Reinserts, at the current position, the character you 
last erased with an EVE command or editing key. 

In overstrike mode, the restored character replaces 
the character the cursor is on. In insert mode, the 
restored character is inserted at the cursor position 
and existing text moves to accommodate it. 


RESTORE LINE 


Reinserts, at the current position, the line that you 
last erased with an EVE command or editing key. 


RESTORE SELECTION 


Reinserts, at the current position, the text last erased 
with a pending delete operation. For more information 
about using pending delete, see Section 8.9. 


RESTORE WORD 


Reinserts, at the current position, the word that you 
last erased with an EVE command or editing key. 
EVE defines GOLD F13 as RESTORE WORD (except 
with the WPS keypad). 


Use the following example to erase and restore text: 

1. Invoke EVE to create the buffer RHYMES.DAT and enter the following text: 

She rhymes with tree, 

also with bee, 

and this one makes three. 

2. Move the cursor to the letter / in the word also. Enter the ERASE LINE 
command. 

EVE erases all characters from the letter / in also to the end of the line and 
appends the next line to the current line. 

She rhymes with tree, 
aand this one makes three. 

3. Move the cursor to the letter y in the word rhymes. Enter the ERASE WORD 
command. 

EVE erases the word rhymes and shifts the remaining text to the left. 

She with tree, 

aand this one makes three. 

4. Move the cursor to the second letter a on the second line. Enter the 
RESTORE LINE command. 

EVE restores the last line that was erased, in this case, Iso with bee,. 

She with tree, 
also with bee, 
and this one makes three. 

5. Move the cursor to the letter w in the word with on the first line. Enter the 
RESTORE WORD command. 

EVE restores the last word that was erased, in this case, rhymes. 

She rhymes with tree, 

also with bee, 

and this one makes three. 


6. To exit from EVE, press Ctrl/Z. 
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Section 8.7.1 describes the functions of the SELECT and REMOVE commands, 
which can be used together to erase text from a buffer. 

8.7.1 Moving Text 

You can use EVE commands to select sections of text for copying, moving, 
deleting, or other editing operations. This section discusses how to move text. 

For information on how to move text from one buffer to another, see Section 8.15. 

You can also select a rectangular area (a box) of text rather than a linear range 
of text to move, erase, or duplicate text. For information about using box editing 
commands, see Section 8.8. 

To move text, follow these steps: 

1. Once you have invoked a file in EVE, place the cursor on the first character 
you want to move. 

2. Press the Select key. 

3. Move the cursor to one character beyond the last character you want to 
move. (I n reverse direction, move the cursor to the last character, not one 
beyond.) The text to be moved is highlighted in reverse video. (If you decide 
not to remove text from the buffer, press the Select key again to cancel the 
selection.) 

4. Press the Remove key. EVE deletes the highlighted text from your screen and 
places it in the I nsert Here buffer. 

5. Press the I nsert Here key to insert text. 

EVE inserts the text at the cursor location. You can insert the text contained 
in the I nsert Here buffer any number of times at any cursor location until you 
select a new section of text and put that new text in the I nsert Here buffer. 
The I nsert Here buffer contains whatever text was last copied or removed. 

6. To exit from EVE, press Ctrl/Z. 

Table 8-7 describes EVE editing keys used to move text. 


Table 8-7 EVE Editing Keys That Move Text 
Key or Key Sequence Function 


I nsert Here 


Remove 


Select 


Same as the INSERT HERE or PASTE command. Inserts, at 
the current position, text that you removed or copied. 

Same as the REMOVE or CUT command. Removes the text 
that is marked with SELECT or highlighted by FIND and 
places it in the I nsert Here buffer. 

Marks text (highlighting it in reverse video) from the initial 
cursor location to wherever you move the cursor. The text that 
is highlighted is called the select range. To cancel the selection, 
press the Select key again or use RESET. 

(continued on next page) 
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Table 8-7 (Cont.) EVE Editing Keys That Move Text 


Key or Key Sequence 

Function 

GOLD Select 

Same as RESET. Cancels any of the following and resets the 

direction of the buffer to forward: 

• Highlighting of a select or found range 

• A press of the GOLD key (or GOLD n combination for a 
repeat count) 

• An incomplete or recalled command line, or Choices buffer 
display 

• The output of SHOW, SHOW DEFAULTS BUFFER, 
SHOW SUMMARY, or SHOW WILDCARDS, thereby 
returning you to the buffer you were working in 

GOLD Remove 

Same as the STORE TEXT or COPY command. Copies text 
that is marked with SELECT or FIND, putting it in the Insert 
Here buffer. Text that is copied is not removed from its original 
position. 


Table 8-8 describes EVE commands used to move text. 

Table 8-8 EVE Commands That Move Text 


Command 

Function 

INSERT HERE 
or PASTE 

Inserts the text you copied or removed. By default, EVE 
defines the E2 key (Insert Here on the mini keypad on VT200, 
VT300, and VT400 series terminals) and the KP9 key (on 
VT100 series terminals) as INSERT HERE. 

REMOVE 
or CUT 

Removes the text that was marked with SELECT or 
highlighted by FIND, and places it in the Insert Here 
buffer. By default, EVE defines the E3 key (Remove on the 
minikeypad on VT200, VT300, and VT400 series terminals) 
and the KP8 key (on VT100 series terminals) as REMOVE. 

RESET 

Cancels any of the following and resets the direction of the 

buffer to forward: 

• Highlighting of a select or found range 

• A press of the GOLD key (or GOLD n combination for a 
repeat count) 

• An incomplete or recalled command line, or Choices buffer 
display 

• The output of SHOW, SHOW DEFAULTS BUFFER, 
SHOW SUMMARY, or SHOW WILDCARDS, thereby 
returning you to the buffer you were working in 

RESTORE SELECTION 

Reinserts the text erased by a pending delete operation. For 
more information about using pending delete, see Section 8.9. 

(continued on next page) 


8-17 


Editing Text Files: Using EVE 
8.7 Erasing and Restoring Text 


Table 8-8 (Cont.) EVE Commands That Move Text 


Command 

Function 

SELECT 

H igh lights text in reverse video from the initial cursor location 
to wherever you move the cursor. The text that is highlighted 
is called the select range. To cancel the selection, enter the 
SELECT command again or use RESET. By default, EVE 
defines the E4 key (Select on the minikeypad on VT200, 
VT300, and VT400 series terminals) and the KP7 key (on 
VT100 series terminals) as SELECT. 

SELECT ALL 

Highlights all text in reverse video in the current buffer 
regardless of the cursor position. The text that is highlighted 
is called the select range. To cancel the selection, enter the 
SELECT command or use RESET. The SELECT ALL command 
temporarily disables pending delete to avoid accidentally 
erasing all of the buffer. 

SET NOPENDING 
DELETE 

Default setting. Disables deletion of selected text when you 
use the Delete key or type new text. If you select text in the 
buffer, typing new text adds characters to the select range and 
using the Delete key erases only the character to the left of the 
cursor. 

SET PENDING 
DELETE 

Enables pending delete, which lets you quickly erase blocks 
of text. First enable pending delete, then use the SELECT 
command to choose the text you want to erase. E rase the text 
by pressing the Delete key (or any other key on the alpha- 
numeric keypad). To reinsert what you deleted, move the 
cursor to where you want the text and enter the RESTORE 
SELECTION command. The default is SET NOPENDING 
DELETE. 

STORE TEXT 
or COPY 

Copies text that was marked with SELECT or FIND, placing 
it in the 1 nsert Here buffer. Text that is copied is not removed 
from its original position. 


To use the Select, Remove, and I nsert Here keys to erase and move text from one 
location to another, follow these steps: 

1. Invoke EVE toeditthefileRHYMES.DAT. 

2. MovethecursortothebeginningofthesecondlineofRHYMES.DAT and 
press the Select key. 

3. Press the down arrow key once. 

The second line of text is highlighted. 

4. Press the Remove key. 

The second line of text is removed from the current buffer. 

She rhymes with tree, 
and this one makes three. 

[End of file] 

5. Press the Return key twice and then press the I nsert Here key. 

The text in the I nsert Here buffer is inserted at the current cursor location. 

She rhymes with tree, 

also with bee, 

and this one makes three. 

[End of file] 
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6. To exit from EVE, press Ctrl/Z. 

8.7.2 Copying Text 

With the COPY command, you can copy text elsewhere. The STORE TEXT 
command is the same as the COPY command. You can substitute the STORE 
TEXT command wherever the COPY command is used in the following example. 

To copy text when the buffer is set in a forward direction, follow these steps: 

1. Invoke EVE toeditthefileRHYMES.DAT. 

2. Move the cursor to the first line of text. 

3. Press the Select key. 

4. Press Ctrl/E to move the cursor to the end of the first line. 

5. Enter the COPY command. The I nsert Here buffer now contains a copy of the 
selected text. 

6. Move the cursor to the line above also with bee,. 

7. Press the I nsert Here key. Your buffer should now look as follows: 

She rhymes with tree, 

She rhymes with tree, 

also with bee, 

and this one makes three. 

[End of file] 

8. Move the cursor to the beginning of the first line of text. Use the Select key 
and then the Remove key to delete the first line of text. 

9. To exit from EVE, press Ctrl/Z. 

8.8 Box Editing 

You can edit text that has rectangular areas, or boxes, as well as standard linear 
ranges. For example, you can select a box containing a list or columns in a table, 
and then cut and paste the box or perform some other editing operation on the 
box. 

8.8.1 Selecting a Box of Text 

To select a box of text, follow these steps: 

1. Put the cursor where you want to start the selection— typically, where you 
want the upper left corner of the box. 

2. Enter the BOX SELECT command. 

3. Move the cursor to where you want the diagonally opposite corner of the 
box— typically, moving from upper left to lower right. 

As you move the cursor, text that you cross is highlighted in bold video (a regular 
selection uses reverse video). The box is defined by diagonally opposite corners. 

If you move from upper left to lower right, the character that the cursor is on is 
outside the box, that is, the lower right corner of the box is left of the cursor. 

You can then edit the box by using any of the editing commands that ordinarily 
work on a linear or a rectangular range. You need not redefine keys. Seethe 
Extensible Versatile Editor Reference Manual for further information. 
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You can use FIND SELECTED if the selection does not cross lines or OPEN 
SELECTED. You can also use pending delete. 

To cancel a box selection, repeat SELECT or BOX SELECT, or use RESET. 

8.8.2 Cutting and Pasting a Box of Text 

Cutting a box usually pads the area with spaces to keep the column alignment of 
text to the right of the box. Pasting a box usually overwrites existing text. Tab 
characters in the box, or that overlap the box, are converted to spaces to keep the 
column alignment of text. 

Table 8-9 lists the EVE commands for box editing. 


Table 8-9 EVE Commands for Box Editing 

Command Function 


BOX COPY 
BOX CUT 

BOX CUT INSERT 

BOX CUT OVERSTRIKE 

BOX PASTE 

BOX PASTE INSERT 
BOX PASTE OVERSTRIKE 
BOX SELECT 

RESTORE BOX SELECTION 
SET BOX NOPAD 
SET BOX NOSELECT 

SET BOX PAD 

SET BOX SELECT 


Copies a box of text without removing it, so you can 
paste it elsewhere. 

Cuts a box of text so you can paste it elsewhere, 
usually padding the area with spaces to keep the 
column alignment of text to the right of the box. 

Cuts a box, making text to the right of the box 
"collapse" to the left, closing the gap. 

Cuts a box, padding the area with spaces to keep the 
column alignment of text to the right of the box. 

Pastes a box of text you copied or cut, usually 
overwriting existing text. 

Pastes a box, pushing existing text to the right. 

Pastes a box, overwriting existing text. 

Selects a box of text. Typically, you start at the 
upper left corner of the box and move the cursor to 
where you want the lower right corner. 

Puts back (undeletes) a box erased with pending 
delete, usually overwriting existing text. 

Disables padding and overstriking for box editing 
unless the buffer is in overstrike mode. 

Default setting. Disables box selection, cutting, and 
pasting. Commands such as SELECT, COPY, and 
REMOVE use standard linear ranges. To edit boxes, 
use BOX commands. 

Default setting. Enables automatic padding and 
overstriking for box editing, regardless of the buffer 
mode. 

Enables box selection, making commands such 
as SELECT, REMOVE, and INSERT HERE the 
same as the corresponding BOX commands, without 
having to redefine keys. 


To select and then cut and paste a box of text, follow these steps: 

1. Invoke EVE tocreatethebufferCITIES.DAT and enter the following text: 

Rome Paris New York 

London Tunis Boston 

Tokyo Bonn Lisbon 
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2. Move the cursor to the left of the letter P in the word Paris. E nter the BOX 
SELECT command. 

3. Move the cursor two spaces to the right of the second letter n in the word 
Bonn — the diagonally opposite corner of the box. The text that you cross is 
highlighted in bold video. Enter the BOX CUT command. 

EVE removes the box of text. 

4. Move the cursor to the right of the column that begins with the words Non 
York. 

5. Enter the BOX PASTE command. 

EVE pastes the box of text into a new column, as follows: 

Rome New York Paris 

London Boston Tunis 

Tokyo Lisbon Bonn 

[End of file] 

If you are going to make several box edits— for example, in editing multicolumn 
tables and lists— use the SET BOX SELECT command. SET BOX SELECT 
redefines several commands and keys as the corresponding BOX commands and 
makes other editing operations work on boxes instead of linear ranges. 

Table 8-10 lists the SET BOX SELECT commands. 


Table 8-10 SET BOX SELECT Commands 


Command 

Effect with SET BOX SELECT 

INSERT HERE or PASTE 

BOX PASTE 

REMOVE or CUT 

BOX CUT 

RESTORE SELECTION 

RESTORE BOX SELECTION 

SELECT 

BOX SELECT 

STORE TEXT or COPY 

BOX COPY 


You can then select, cut, and paste a box by using the Select, Remove, and I nsert 
Here keys, without having to redefine the keys. 

8.9 Using Pending Delete 

You can use pending delete to erase selected text. Pending delete refers to 
erasing a selection by typing new text, pressing the space bar, or by using delete 
(typically, pressing the Delete key). 

With a box selection, pending delete works like BOX CUT, usually padding the 
area with spaces to keep the column alignment of text to the right of the box. 

8.9.1 Erasing a Selection with Pending Delete 

To erase a selection using pending delete, follow these steps: 

1. I nvoke a file in EVE. 

2. To enable pending delete, use the SET PENDING DELETE command. The 
default setting is SET NOPENDING DELETE. 

3. Select the text you want to erase. You can use SELECT or BOX SELECT. 
(You cannot use SELECT ALL.) 
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4. Type new text or use the DELETE command. 

Pending delete gives you an alternative way of cutting and pasting text because 
pending delete does not use the I nsert Here buffer. For more information about 
pending delete, seethe EVE online help topic called Pending Delete. 

8.9.2 Restoring a Selection That Was Erased with Pending Delete 

To put back (restore) the text you erased with pending delete, follow these steps: 

1. Put the cursor where you want to restore the text. If restoring a box selection, 
put the cursor where you want the upper left corner of the box to be. 

2. Use RESTORE SELECTION. If a box selection was erased with pending 
delete, use RESTORE BOX SELECTION. If you used SET BOX SELECT, you 
can use RESTORE SELECTION (without having to redefine a key). 

Restoring a box works like BOX PASTE, usually overwriting existing text. When 
using the SET BOX NOPAD command, the effects of box editing depend on the 
mode that the buffer is in (insert or overstrike, as shown in the status line): 

• I n insert mode, cutting a box makes text to the right of the box "collapse" 
to the left, closing the gap. Tab characters to the right of the box are also 
converted to spaces to keep the column alignment as the text collapses to the 
left. This method is useful for removing columns from a table or list, such 
as in turning a 4-column table into a 2-column table. Pasting a box pushes 
existing text to the right, which is useful for adding columns in the middle of 
a table. 

• I n overstrike mode, cutting a box pads the area with spaces to keep the 
column alignment of text to the right of the box. Pasting a box overwrites 
existing text. The effects are the same as with SET BOX PAD, which is the 
default setting. 

The buffer mode also affects erasing a box with pending delete and restoring an 
erased box. 

8.10 Finding and Replacing Text 

With EVE commands, you can search for specific text in a buffer. You can search 
for every occurrence of specific text, and you can search for text that is on a single 
line or spans a line break. Also, you can search for text using wildcards. This 
section describes methods for searching and replacing text. 

Table 8-11 describes the EVE commands that locate text in a buffer. 

Table 8-11 EVE Commands for Locating Text in a Buffer 
Command Function 

FIND Searches the current buffer for the text string you specify 

and highlights the found text. The text that is highlighted 
is called the found range. 

FIND NEXT Searches for the string of text you last specified with the 

FIND, REPLACE, or WILDCARD FIND command. 

(continued on next page) 
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Table 8-11 (Cont.) EVE Commands for Locating Text in a Buffer 


Command 

Function 

FIND SELECTED 

Searches for a string of text you have selected, rather 
than for a typed string. The selection cannot cross more 
than one line. 

SET FIND CASE EXACT 

Enables case-exact searches. This is particularly useful to 
find or replace search strings in lowercase letters only. 

SET FIND CASE NOEXACT 

Default setting. Disables case-exact searches so that EVE 
finds any occurrence if you enter a search string in all 
lowercase letters. 

SET FIND NOWHITESPACE 

Default setting. Sets FIND and WILDCARD FIND 
commands to match tabs and spaces exactly as you 
specify in the search string, and to search for strings that 
are entirely on one line. 

SET FIND WHITESPACE 

Sets FIND and Wl LDCARD FIND commands to treat 
spaces, tabs, and up to one line break as "white space" so 
you can search for strings of two or more words regardless 
of how they are separated. 

SET WILDCARD VMS 

Default setting on OpenVMS. Enables OpenVMS patterns 
for WILDCARD FIND. 

SHOW WILDCARDS 

Lists the wildcard patterns you can use with Wl LDCARD 
FIND. 

WILDCARD FIND 

Searches for a pattern of text, using wildcards. 


8.10.1 Finding Text 

Use the FIND command to locate specific text in the current buffer. By default, 
EVE defines the El key (Find key on VT200, VT300, and VT400 series terminals 
and the PF1 key on VT100 series terminals) as the FIND command. 

If the search string contains all lowercase letters, EVE disregards the case of 
letters and locates any occurrence of the string. Thus, the search string the 
matches the, THE , THe, and thE. If the search string contains one or more 
uppercase letters, EVE finds only the occurrences of the string in which the case 
of each letter is exactly the same. Therefore, the only match for the search string 
tHis is tHis. For example: 

1. Enter the FI ND command. 

2. Type the text (called the search string) that you want to locate. 

The current direction of the buffer determines whether EVE first searches in a 
forward or reverse direction. 

If EVE cannot find the string in the current direction but finds it in the opposite 
direction, EVE prompts you to change direction. 

To search in the opposite direction, type Y and press the Return key. EVE moves 
the cursor to the first occurrence of the string in the opposite direction. The 
current direction in the highlighted status line does not change, however. 

When EVE finds the search string, the editor highlights it and moves the cursor 
to the first letter of the string. See the Extensible Versatile Editor Reference 
Manual for a listing of the editing commands you can use on a highlighted search 
string. 
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To cancel the highlighting, move the cursor off the search string or use the 
RESET command. 

To find the next occurrence of the search string, press the Find key twice or enter 
the FIND NEXT command. 

8.10.2 Setting Case-Exact Searches 

If you want to match the case of your search exactly when searching for lowercase 
occurrences of a string, enter the SET FIND CASE EXACT command. Then when 
you enter a search string in all lowercase letters, EVE searches only for lowercase 
occurrences, skipping occurrences that contain uppercase letters. For example, 
the following commands enable case-exact searching and then find digital when it 
appears in lowercase only, skipping occurrences such as Digital or DIGITAL : 

Command: SET FIND CASE EXACT 
Command: FIND digital 

The setting applies to the FIND, REPLACE, and Wl LDCARD FIND commands. 
You can save the setting in your section file or command file for future editing 
sessions. The default setting is SET FIND CASE NOEXACT. 

EVE is sensitive to diacritical (accent) marks and locates only those occurrences 
of the string in which the diacritical marks are exactly the same. For example, in 
searching for e, EVE does not find occurrences of e, e, e, or e. 

To use the FIND command with the existing file RFIYMES.DAT, follow these 
steps: 

1. I nvoke EVE to edit RHYMES.DAT. The cursor appears on the first letter of 
the first line of the buffer, and the current direction is forward. 

2. Press the Find key, type the letters ree, and press the Return key. The cursor 
moves to the letter r in the word tree and highlights the letters ree. 

3. Press the Find key twice to find the next occurrence of the string ree. The 
cursor moves to the letter r in the word three and highlights the letters ree. 

When a search string is found and highlighted, you can use any command 
that works on a selected or found range except SPELL. Also, you cannot use 
a pending delete operation on a found range. 

4. Enter the UPPERCASE WORD command. 

The UPPERCASE WORD command changes the case of the highlighted 
letters from lowercase to uppercase, as shown in the following example: 

She rhymes with tree, 

also with bee, 

and this one makes thREE. 

[End of file] 

To use FIND SELECTED to search for a string that is particularly complicated or 
is easily misspelled or mistyped, follow these steps: 

1. Copy the text so that it is appears twice in the buffer. 

2. M ove the cursor to the beginning of the string rhymes with tree, on the first 
line. 

3. Enter the SELECT command. 

4. Move the cursor to highlight the string and select text. Note that the selection 
cannot span more than one line. 
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5. Enter the command FI ND SELECTED. 

The cursor moves to the next occurrence of the string rhymes with tre$. The 
selection is canceled and the found string appears in bold video. 

8.10.3 Using Wildcards 

You can use wildcards to search for text. The SHOW Wl LDCARDS command 
displays wildcard patterns for the current wildcard setting. To use wildcards, 
follow these steps: 

1. Position the cursor at the beginning of the buffer. 

2. Enter the command Wl LDCARD FI ND *eeto search for text strings ending 
in ee. 

She rhymes with tree, 

also with bee, 

and this one makes thREE. 

[End of file] 

EVE puts the cursor at the beginning of the line containing the r in tree. 

8.10.4 Including White Space in a Search 

Use the SET FIND WHITESPACE and SET FIND NOWHITESPACE commands 
to specify how the Wl LDCARD FIND and FIND commands treat the blank spaces 
between words, such as spaces, tabs, and line breaks. 

The SET FIND NOWHITESPACE command enables the commands to search for 
multiword strings on a single line, matching spaces and tabs exactly as they are 
found. SET FIND NOWHITESPACE is the default search behavior. 

The SET FIND WHITESPACE command enables the Wl LDCARD FIND and 
FIND commands to search for a string of two or more words regardless of how 
they are separated. It enables the FIND commands to search for a string that 
contains a single line break and more than one space or tab between words. 

8.10.5 Marking Locations in Text 

The MARK and GO TO commands are useful for editing a large file and then 
returning to a specific location later in the editing session. The following table 
describes the MARK and GO TO commands: 


Command 

Function 

MARK 

Puts an invisible mark at the current cursor position. The mark exists 
for the rest of an editing session or until you change it; it is not saved 
when you exit. 

GO TO 

Returns the cursor to the location labeled by the MARK command. If 
the labeled location is found in another buffer, EVE moves the cursor 
to the other buffer and puts that buffer into the current window. 


To mark your position, enter the MARK command followed by a label name of 
your choice. The label name can be one or more printable characters, including 
alphanumeric and punctuation characters, spaces, and tab characters. To return 
the cursor to the marked location, enter the GO TO command followed by the 
label name. 
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8.10.6 Replacing Text 

With the REPLACE command, you can replace a text string in the current buffer 
with another text string. This is useful if you have spelled a word incorrectly 
throughout a long file and you want to fix every occurrence of the misspelled 
word. 

The REPLACE command is case sensitive. If the old string has any uppercase 
letters, EVE searches for exact case matches. If the old string is all lowercase, 
EVE searches for any occurrence of the string regardless of its case. If the new 
string has any uppercase letters, EVE replaces the string exactly. If the old and 
new strings are all lowercase, EVE replaces the string according to the following 
rules: 

• A capitalized version of the old string (first letter uppercase, others lowercase) 
is replaced by a capitalized version of the new string. 

• An all-uppercase version of the old string is replaced by an all-uppercase 
version of the new string (otherwise, the old string is replaced by an all- 
lowercase version of the new string). 

The following table shows how EVE uses the case of the strings: 


Old String 

New String 

Highlight 

Replacement 

butter 

margarine 

butter 

margarine 



Butter 

Margarine 



BUTTER 

MARGARINE 



BUtteR 

margarine 

Butter 

margarine 

Butter 

margarine 

butter 

Margarine 

butter 

Margarine 



Butter 

Margarine 



BUTTER 

Margarine 



BUtteR 

Margarine 

Butter 

Margarine 

Butter 

Margarine 


If you want to find or replace only lowercase occurrences of a string, enter the 
SET FIND CASE EXACT command. Then if you enter a search string in all 
lowercase, EVE searches for only lowercase occurrences, skipping occurrences 
that contain uppercase letters. The setting applies to FIND, REPLACE, and 
WILDCASE FIND commands. 

The following table shows how EVE searches for and replaces only lowercase 
strings when you enter the SET FIND CASE EXACT command: 


Old String 

New String 

Highlight 

Replacement 

butter 

margarine 

butter 

margarine 


The default case setting is SET FIND CASE NOEXACT. 
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The following table shows the responses and their effect to the REPLACE 
command query: 


Response 

Effect 

Yes 

Replace this occurrence and find the next one. This is the default 
response - just press the Return key. 

No 

Skip this occurrence and find the next one. 

All 

Replace all occurrences (no further prompting unless EVE finds an 
occurrence in the opposite direction). 

Last 

Replace this occurrence and stop here. 

Quit 

Skip this occurrence and stop here. 


8.11 Advanced Features 

The following sections discuss advanced EVE editing techniques such as: 

• U si ng command I i ne qual ifiers 

• J ournaling and recovering 

• Using advanced EVE formatting commands 

• Using buffers 

8.12 Using Command Line Qualifiers 

When you invoke EVE, you can use command-line qualifiers to specify advanced 
EVE editing features. Table 8-12 lists the qualifiers that you can use with the 
EDIT/TPU command to invoke EVE. 


Table 8-12 EDIT/TPU Command Line Qualifiers 


Qualifier 

Default 

Command file 

/COMMAND=TPU$COMMAND.TPU 

File creation 

/CREATE 

Debugging package 

/NODEBUG 

Specifying display mode 

/Dl SPLAY =CHARACTER_CELL 

1 nitialization file 

/I N ITI ALIZATI ON=EVE$INIT.EVE 

J ournaling 

/J OURNAL 

Modifying main buffer 

/MODIFY 

Specifying output 

/OUTPUT =output-file 

Read-only access 

/NOREAD_ONLY 

Recovery 

/NORECOVER 

Section files 

/SECTI ON =TPU$SECTI ON 

Start position 

/START_POSITI ON =(1,1) 

Work file 

/WORK=SYS$SCRATCFI:TPU$WORK.TPU$WORK 


When using the character-cell screen updater, the default insert or overstrike 
mode is determined by your terminal setting. 
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8.12.1 Starting in an Alternate Position 

Start position qualifiers determine the row and column where the cursor first 
appears in the buffer that you specified on the command line. 

For EVE, the default start position is 1,1— row 1, column 1, which is the upper 
left corner of the buffer. Use of start position qualifiers does not affect the initial 
cursor position when you create another buffer during the editing session and 
does not limit the buffer size. The format of the start position qualifier is as 
follows: 

/START_POSITION=(row[, column] 

The fields are as follows: 

/START_POSITI ON You must use the /START_POSITION = qualifier to the 

EDIT/TPU command. 

row The row that you want the cursor to be at when you invoke EVE . 

column The column that you want the cursor to be at when you invoke 

EVE. 

Use the start position qualifier to begin editing at a particular line (or row) or at 
a particular character position (or column). For example, when you want to skip 
over a standard heading in a file or if a batch log file or error message tells you 
there is an error on a given line of a program, you can specify that line number as 
the starting row so that when you edit the program source file, the cursor moves 
directly to that line. The following command edits a file named test.com and puts 
the cursor on line 10, column 5: 

$ EDIT/TPU TEST.COM /START_P0SITI0N= (10, 5) 

If you want to start at a particular line in a file, you can omit the second 
parameter (the column). 

8.12.2 Using a Work File 

Work file qualifiers determine the work file that is used to swap memory for 
editing very large files. There is one work file per editing session. The work file 
is a temporary file that is automatically deleted when you exit. 

The default work file is named TPU$WORK.TPU$WORK. EVE creates the work 
file in SYS$SCRATCFI unless you specify otherwise. There are two ways to 
specify a different work file: 

• Define the logical name TPU$WORK. 

This is useful if you want the work file to be created in an area other than 
SYS$SCRATCFI, such as on a larger disk. You can put the definition in your 
LOGIN.COM file. 

• Use the /WORK = qualifier and specify the work file. 

This overrides any definition of theTPU$WORK logical name. For example, 
the following command invokes EVE and specifies the work file to be 
SYS$SCRATCH:MYWORK.TPU$WORK: 

S EDIT/TPU /W0RK=MYW0RK 

If you want the work file to be created in an area other than SYS$SCRATCH, use 
a complete file specification, including the device (disk) and directory. You cannot 
use wildcards to specify the work file. 
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8.12.3 Modifying the Main Buffer 

Modifying qualifiers determine whether you can modify the buffers specified on 
the command line. Modifications do not affect other buffers you create during the 
editing session. 

By default, you can modify the buffer by editing text in it. When you exit, EVE 
writes out the buffer to a file if the buffer has been modified. 

Use /NOMODI FY to examine a file without making any changes. You can then 
use cursor-movement commands but you cannot change the text. 

If you specify neither /MODIFY nor /NOMODI FY, your application determines if 
you can modify the buffer. EVE's default behavior is to modify the buffer. 

Use /MODIFY to override the effect of /READ_ONLY or /NOWRITE. Use 
/MODIFY with /READ_ONLY or /NOWRITE to practice editing operations 
without writing a file on exiting. For example, the following command invokes 
EVE, making the buffer you specified on the command line read-only (or no-write) 
and making it modifiable: 

$ EDIT/TPU /READ_0NLY /MODIFY 

In EVE, you can set or change the modification attribute of the buffer by using 
SET BUFFER commands. 

8.12.4 Alternate Methods to Invoke EVE 

This section contains alternate methods to invoke EVE. 

8.12.5 Invoking EVE from a Search List 

You can use a search list to invoke EVE to edit a file from that search list. For 
example: 

$ DEFINE STAFFMEMOS HIRING . DAT, PROMOTION . LIS, SALARY . TXT 
$ EDIT/TPU STAFFMEMOS 

In the above example, if the first file in the search list exists, EVE copies 
that file (H I Rl NG.DAT) into a buffer and uses the file name and file type as 
the buffer name. If the file does not exist, EVE tries to get the second file 
(PROMOTION .LIS), and so on. If none of the files in the search list exists, EVE 
creates an empty buffer named H I Rl NG.DAT because that is the first file in the 
search list. 

8.12.6 Invoking EVE with Wildcards 

When you invoke EVE to edit an existing file, you can use the asterisk (*) 
wildcard character as a substitute for some or all of the characters in the file 
name and file type. To use wildcards in EVE, follow the same rules as using 
wildcards in DCL. You can use the percent (%) wildcard character as a substitute 
for a single character at a time, and you can use the ellipsis ([...]) wildcard 
character as a substitute for a directory specification. If only one match is made, 
the file is displayed on your screen. If more than one match is made, EVE 
displays a list of matching files and prompts you to provide a more complete file 
specification. If no match is made, EVE creates a buffer named Main. 

To invoke EVE with wildcards, enter the following command: 

$ EDIT/TPU * . TXT 
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If more than one file matches your wildcard request, EVE displays the matching 
files so you can choose the one you want. For example, if you specify *.TXT, two 
files (LETTER.TXT and MEMO.TXT) match your wildcard request. In this case, 
EVE gives you a list in a second window in a system buffer named $CHOICES$. 

If no matching file is found, EVE creates an empty buffer named Main. 

If you use a search list or wildcard directory to specify an input file, EVE gets 
the first matching file found without displaying the $CHOICES$ buffer. For 
information about using the $CFIOICES$ buffer, seethe EVE online help topic 
called Choices Buffer. 

8.12.7 Invoking EVE with a Wildcard Directory Name 

To use a wildcard in a directory name ([...]) to invoke EVE, use the syntax for 
your system. You can work in your current directory or in a subdirectory of the 
current directory. For example: 

$ EDIT/TPU [ . . .] PINK. TXT 

EVE searches through the directory tree and gets the first PINK.TXT file found, 
if there is one. 

This way of handling a search list or wildcard directory applies not only to the 
EDIT/TPU command, but also to EVE commands that use a file specification as a 
parameter. The following EVE commands use a file specification as a parameter: 

@(at sign) 

GET FILE 
INCLUDE FILE 
OPEN 

OPEN SELECTED 
RECOVER BUFFER 

8.12.8 Invoking EVE with Multiple Input Files 

You may specify multiple input files on the command line that invokes EVE. 

The files must be separated by commas with optional white space. If wildcard 
characters are present in the file names, EVE displays the matching files for 
only the first wildcarded file name that has more than one match. For the other 
ambiguous file names, EVE outputs a warning message. 

8.13 Journaling and Recovery 

J ournal files record your edits so that if a system failure interrupts your editing 
session, you can recover your work. 

Buffer-change journaling creates a separate journal file for each text buffer 
you create. This is the EVE default. Buffer-change journaling works both on 
DECwindows and on character-cell terminals. You recover one buffer at a time, 
typically by using RECOVER BUFFER commands in EVE. You can recover 
buffers from different editing sessions. The recovery restores only your text— it 
does not restore settings, key definitions, or the contents of system buffers (such 
as the I nsert Here buffer) before the system failure. 

You can disable journaling when you invoke EVE by using the /NOJ OURNAL 
qualifier on your command line. This is useful when you use EVE to examine a 
file without making any edits or for demonstration sessions. 
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8.13.1 Using Buffer-Change Journaling 

Buffer-change journaling creates a journal file for each text buffer. (EVE does 
not create buffer-change journal files for system buffers such as the I nsert Here 
buffer, DCL buffer, or $RESTORE$ buffer.) As you edit a buffer, the journal file 
records the changes you make, such as erasing, inserting, or reformatting text. 
When you exit from EVE or when you delete the buffer, the journal files are 
deleted. If a system failure interrupts your editing session, the journal files are 
saved. Your last few keystrokes before the system failure may be lost. Table 8-13 
summarizes the EVE commands for buffer-change journaling and recovery. 


Table 8-13 EVE Commands for Buffer-Change Journaling and Recovery 


Command 

Function or Effect 

RECOVER BUFFER 

Recovers a specified buffer by using the journal file for 
the buffer. You can specify the name of the buffer or 
file you want to recover or the name of the journal file 
for the buffer. 

RECOVER BUFFER ALL 

Recovers all your text buffers, one at a time, by using 
the journal files for the buffers, if there are any. 

SET J OURNALING 

Enables buffer-change journaling for a buffer that you 
specify. 

SET J OURNALING ALL 

Enables buffer-change journaling for all your buffers. 
This is the default setting. 

SET NOJ OURNALING 

Disables buffer-change journaling for a buffer you 
specify. 

SET NOJ OURNALING ALL 

Disables buffer-change journaling for all your buffers. 


Buffer-change journal files are written in a directory defined by the logical name 
TPU$J OURNAL. By default, this directory is SYS$SCRATCH, which is typically 
your top-level (login) directory. You can redefine the TP U$J OURNAL logical 
name to have the journal files written to a different directory. For example, the 
following commands create a subdirectory called [USER.J OURNAL] and then 
defineTPU$J OURNAL as this subdirectory: 

$ CREATE/DIRECTORY [USER. JOURNAL] 

$ DEFINE TPUS JOURNAL [USER. JOURNAL] 

You can put the definition in your LOGIN.COM file. 

Buffer-change journal files may be quite large (even larger than the text files 
you edit). Because of the potential size of buffer-change journal files and 
because there is a journal file for each text buffer, you may want to define 
TPU$J OURNAL as a directory or subdirectory on a large disk, rather than as 
SY S$SCRATCH . 

Deriving Buffer-Change Journal Names 

Buffer-change journal file names are derived from the name of the file or buffer 
being edited and the default file type for the operating system. Table 8-14 shows 
the buffer-change journal file names. 
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Table 8-14 Buffer-Change Journal File Names 


Text Buffer Name 


Buffer-Change Journal File 


J ABBER.TXT 

GUM BO_RECI PE .RNO 

MAIN 

LATEST NEWS 


J ABBER_TXT.TPU$J OURNAL 
GUMBO_RECIPE_RNO.TPU$J OURNAL 
MAI N.TPU$J OURNAL 
LATEST_NEWS.TPU$J OURNAL 


To find out the name of the journal file for the current buffer, enter the SHOW 
command at the EVE prompt. The SHOW command will display the name of 
your input file, output file, your journal file, and other information about your 
current buffer. 

Using Buffer-Change Journaling to Recover 

There are two ways to recover your edits with buffer-change journal files: 

• Use the /RECOVER qualifier on the EDIT/TPU command line when you 
invoke EVE. 

• Use RECOVER BUFFER commands within EVE. 

Using the /RECOVER Qualifier 

I n the following example, you are editing a file named J ABBER.TXT when a 
system failure interrupts your editing session. You then use system recovery to 
recover your edits. 

$ EDIT/TPU JABBER.TXT 


*** system failure * • * *** 


$ EDIT/TPU JABBER. TXT/RECOVER 

Using the RECOVER BUFFER Command 

To use the recover buffer command, follow these steps: 

1. I nvoke EVE and enter the following command to recover your text: 

Command: RECOVER BUFFER JABBER.TXT 

If the buffer-change journal file is available, EVE shows the following 
information and asks if you want to recover that buffer: 

Name of the buffer 

Original input file for the buffer, if any 
Output file for the buffer, if any 
Source file for recovery, if any 
Starting date and time of the editing session 
J ournal file creation date and time 

2. Press the Return key to recover your buffer. 

If you do not want to recover your buffer, type No and press the Return key. 

If you delete or rename the source file for recovery, the recovery fails. The 
source file is either the file initially read into the buffer (if any) or the last file 
written before the system failure. 
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If the buffer you want to recover exists (usually the Main buffer), EVE first 
deletes that buffer and then does the recovery. If the buffer you want to 
recover has been modified, EVE asks you whether to delete the buffer before 
recovering. 

Recovery When You Are Unsure of the File Name 

If you are unsure of the buffer names or journal file names, specify the asterisk 
(*) wildcard, as follows: 

Command: RECOVER BUFFER * 

EVE then displays a list of all your available journal files so you can choose the 
one you want. The list appears in an EVE system buffer named $CHOICES$ in a 
second window. For information about using the $CHOICES$ buffer, seethe EVE 
online help topic called Choices Buffer. 

Recovering All Buffers 

To recover all your text buffers— one at a time— use the RECOVER BUFFER ALL 
command. EVE then tries to recover each text buffer for which there is a buffer- 
change journal available. The effect is the same as repeating the RECOVER 
BUFFER command without having to specify buffer names or journal file names. 
For each text buffer, EVE displays information such as the buffer name, the files 
associated with the buffer, and the time and date the journal file was created. 
EVE prompts you for one of the following: 


Response 

Effect 

Yes 

Recovers the buffer and then asks you whether to recover the next 
buffer, if there is one. This is the default response— just press the 
Return key. 

No 

Skips this recovery. If there is another buffer to recover, EVE asks you 
about the other buffer. 

Quit 

Cancels— does not recover the buffer and does not continue recovery 
operations. 


Disabling Buffer-Change Journaling 

You can disable buffer-change journaling for a particular buffer by using the SET 
NOJ OURNALING command. To disable buffer-change journaling for all your 
buffers, use the SET NOJ OURNALING ALL command. 

For example, to delete all the buffer-change journal files, use the following 
command: 

S DELETE TPU$ JOURNAL :*.TPU$ JOURNAL;* 

Enabling Buffer-Change Journaling 

If you disabled buffer-change journaling, you can enable journaling by using the 
SET J OURNALI NG command. The following command enables journaling for a 
buffer namedJABBER.TXT: 

Command: SET JOURNALING JABBER.TXT 

If you invoked EVE without journaling and then want to enable buffer-change 
journaling during the editing session, use the SET J OURNALI NG ALL command 
(which is the EVE default). 
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You cannot enable buffer-change journaling if the buffer has been modified. In 
such a case, EVE displays the following message: 

Command: SET JOURNALING MEMO . TXT 

Buffer MEM0.TXT is not safe for journaling 

You should first write out (save) the buffer by using the WRITE FILE or SAVE 
FILE command and then enable journaling. 

8.14 Using advanced EVE formatting commands 

EVE provides commands that let you format your text by setting margins, tabs, 
and word wrap. You can center lines, take extra white space out of text, and 
insert page breaks. 

Table 8-15 shows EVE editing keys and describes their functions. 


Table 8-15 EVE Editing Keys and Their Functions 


Key or Key Sequence 

Function 

Return or Ctrl/M 

1 nserts a carriage return at the current position either 
to start a new line of text or to terminate a command 
you are typing. On VT200, VT300, and VT400 series 
terminals, EVE also defines the Enter key as Return. 

Tab or Ctrl/I 

1 nserts a tab character at the current position according 
to the tab modes and at the tab stops currently set. 

Ctrl/L 

1 nserts a form-feed character at the current position 
to mark the beginning of a new page. A page break 
appears as a small double F (Fp. ) and is always on a line 

by itself. Same as INSERT PAGE BREAK. 

Table 8-16 shows EVE text formatting commands and describes their functions. 

Table 8-16 EVE Text Formatting Commands and Their Functions 

Command 

Function 

CAPITALIZE WORD 

Changes the case of a word, making the first letter 
uppercase and the rest of the letters lowercase. Works 
on a range, box, or single word. 

CENTER LINE 

Centers the current line between the left and right 
margins. The cursor moves with the line, remaining on 
the same character as the line moves. 

CONVERT TABS 

Converts tab characters to the appropriate number of 
spaces in a box, a range, or the entire buffer. 


(continued on next page) 
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Table 8-16 (Cont.) EVE Text Formatting Commands and Their Functions 


Command 

Function 

FILL 

Reformats the current paragraph, range, or box 
according to the margins of the buffer, so the maximum 
number of words fits on a line. When you fill a select 
range or found range, the FILL or FILL RANGE 
command does not reformat a line that begins with 
a page break, a DIGITAL Standard Runoff (DSR) 
command, or DOCUMENT tag; it does reformat the 
other lines in the range. Filling a range does not delete 
blank lines. For more information about select range, 
see Section 8.7.1. 

FILL PARAGRAPH 

Reformats the paragraph the cursor is in according 
to the margins set for the buffer. When you fill a 
paragraph, the FILL command does not reformat a 
line that begins with a page break, DSR command, or 
DOCUMENT tag; it does reformat the other lines in the 
paragraph. 

FILL RANGE 

Reformats the range or box according to the current 
margin settings. When you fill a select range or found 
range, the FILL or FILL RANGE command does not 
reformat a line that begins with a page break, DSR 
command, or DOCUMENT tag; it does reformat the 
other lines in the range. Filling a range does not delete 
blank lines. 

INSERT PAGE BREAK 

Inserts a form-feed character at the current position 
to mark the beginning of a new page. A page break 
appears as a small double F (Fp ) and is always on a line 

by itself. By default, Ctrl/L is defined as INSERT PAGE 
BREAK. 

LOWERCASE WORD 

Changes the current word, range, or box to lowercase. 

PAGINATE 

Inserts a "soft" page break for a 54-line page. A soft 
page break appears as a form feed followed by the null 
character— (Fp l\^ ). When you enter the PAGINATE 

command, EVE moves back to the previous page break 
(if any) then checks ahead for page breaks within the 
next 54 lines. If any soft breaks are found within those 
54 lines, EVE removes them. EVE then moves down 54 
lines, inserts a soft break, and puts the cursor on the 
next line. The soft break is inserted on a line by itself. 

If a hard page break (form feed only) is found within the 
54 lines, EVE stops on the line after the hard break, in 
case you want to erase the break. 

SET LEFT MARGIN 

Sets the left margin in the current buffer. The left 
margin must be greater than 0 but less than the right 
margin. By default, the left margin is 1 (leftmost 
column). 

SET RIGHT MARGIN 

Sets the right margin for the current buffer. The right 
margin must be greater than the left margin. By 
default, the right margin is one less than the width. 

The width is typically 80, so the default margin is 
typically 79. 

(continued on next page) 
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Table 8-16 (Cont.) EVE Text Formatting Commands and Their Functions 

Command Function 


SET PARAGRAPH INDENT 

SET TABS AT 

SET TABS EVERY 

SET TABS INSERT 

SET TABS MOVEMENT 

SET TABS SPACES 

SET TABS INVISIBLE 
SET TABS VISIBLE 
SET NOWRAP 

SET WRAP 

UPPERCASE WORD 


Specifies the number of spaces to be added to or 
subtracted from the first line of paragraphs you create 
or reformat. The default is 0 (no indent). 

Sets tab stops at the columns that you specify. The 
column numbers must be in ascending order and 
separated by spaces. By default, tab stops are set 
every eight columns. The command does not affect the 
hardware tab settings of your terminal. 

Sets tab stops at the specified interval. By default, tab 
stops are set every eight columns. The command does 
not affect the hardware tab settings of your terminal. 

Default setting. Changes the tab mode so that EVE 
inserts a tab character at the current column when you 
press the Tab key. The cursor and text move to the next 
tab stop. 

Changes the tab mode so the Tab key becomes a cursor- 
movement key. Pressing the Tab key moves the cursor 
to the next tab stop but does not insert a tab character. 

Changes the tab mode to insert an appropriate number 
of spaces, rather than a tab character, when the Tab key 
is pressed. Previously existing tab characters are not 
affected. 

Default setting. Makes tab characters invisible on the 
screen, appearing as white space. 

Makes tab characters visible on the screen, appearing as 
a small H|_ (horizontal tab). 

Disables word wrapping at the right margin of the 
buffer. To start new lines, press the Return key or use 
the FILL command. 

Default setting. Enables word wrapping at the right 
margin of the buffer. EVE starts new lines without your 
pressing the Return key or using the FILL command. 

Changes the current word, range, or box to uppercase. 


8.15 Using Buffers 

Buffers are storage areas that exist only during an editing session. Table 8-17 
describes the EVE commands used to create, manipulate, and delete buffers. For 
more information about using EVE commands, seeth e Extensible Versatile Editor 
Reference Manual . 

Table 8-17 EVE Commands to Manipulate Buffers 

Command Function 

BUFFER Puts the specified buffer into the current window and moves 

the cursor to the last location it occupied in that buffer. If the 
specified buffer does not exist, creates a new buffer. 

(continued on next page) 
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Table 8-17 (Cont.) EVE Commands to Manipulate Buffers 

Command Function 


DELETE BUFFER 

GET FILE 
or OPEN 

GO TO 

INCLUDE FILE 

NEW 

NEXT BUFFER 

OPEN SELECTED 

REMOVE 
or CUT 

SAVE FILE 

SAVE FILE AS 


SELECT 
or RETURN 


Deletes a buffer you specify by name. 

Puts the specified file into the current EVE window, creating 
a new buffer if necessary. If the file exists, EVE copies it into 
a new buffer in the current window. If the file does not exist, 
EVE creates a new, empty buffer, using the file name and file 
type for the buffer name. If there already is a buffer by that 
name, EVE asks for a different name to use. 

Returns the cursor to the location labeled by the MARK 
command. If the labeled location is found in another buffer, 
EVE moves the cursor to that buffer and puts it into the 
current window. (Section 8.15.5 explains how to use multiple 
buffers in an editing session.) 

I nserts the contents of the specified file into the current buffer 
at the line above the cursor location. This is useful to combine 
files. 

Creates a new buffer named Main and puts it into the current 
window. If the buffer Main already exists, EVE asks for a 
name for the new buffer. 

Puts the next buffer (if one exists) into the current window 
and moves the cursor to the last position it occupied in that 
buffer. This command lets you move from one buffer to another 
without specifying a buffer name. 

Opens a file whose name you have selected or found. This 
command is the same as using the GET FILE or OPEN 
command without having to type the file name. 

If you are in the Buffer List buffer, same as DELETE 
BUFFER. Use the REMOVE command as follows to delete 
a buffer without typing the buffer name: enter the SHOW 
BUFFERS command (which puts you in the Buffer List buffer), 
move the cursor to the name of the buffer you want to delete, 
and enter the REMOVE command. 

Writes the contents of the current buffer to the file associated 
with the buffer without ending the editing session. If you do 
not specify a file name with the SAVE FILE command, EVE 
prompts you for an output file specification. Similar to WRITE 
FILE. 

Writes the contents of the current buffer to the file you 
specify without ending the editing session. For example, if 
you are editing a file named FIRST.DAT, you can save it as 
SECOND.TXT. This command does not change the name of the 
buffer. It does, however, associate the buffer with the file you 
name so that any subsequent SAVE FILE, WRITE FILE, or 
EXIT command writes the buffer to the file you named. This 
command requires you to supply a file specification. 

If you are in the Buffer List buffer, selects the buffer you 
specify. Use the SELECT command as follows to select a buffer 
without typing the buffer name: enter the SHOW BUFFERS 
command, move the cursor to the name of the buffer you want 
to select, and enter the SELECT command. 

(continued on next page) 
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Table 8-17 (Cont.) EVE Commands to Manipulate Buffers 


Command 

Function 

SET BUFFER 

Lets you specify the editing status of the buffer: whether the 
buffer can be modified or can be written to a file when you exit 
from EVE. 

SHOW 

Displays information about the buffers you have created during 
the editing session. If more than one buffer is active in your 
editing session, the SHOW command displays information 
about the buffer you are currently editing. For information 
about the other active buffers, press the Do key. To resume 
editing, press any other key. 

SHOW BUFFERS 

Lists the buffers you have created during an editing session. 
You can move the cursor through the list and specify a 
particular buffer for viewing by pressing the Select key. 

SHOW DEFAULTS 
BUFFER 

Shows information, such as margins, tab stops, direction, 
mode, and maximum lines, about the EVE system buffer 
named $DEFAULTS$. These are the default settings used 
when you create new buffers. 

SHOW SYSTEM 
BUFFERS 

Lists the system buffers created by EVE, such as the Message 
buffer, Help buffer, Insert Here buffer, and $RESTORE$ buffer. 
You can move the cursor through the list and specify a buffer 
for viewing by pressing the Select key. 

WRITE FILE 

Writes the contents of the current buffer to the file associated 
with the buffer or to the file you specify on the command line 
without ending the editing session. If the current buffer does 
not have a file specification associated with it, EVE prompts 
you for an output file specification. Similar to SAVE FILE. 


When you edit an existing file, EVE reads the contents of the file into a buffer. 
The highlighted status line contains the name of the buffer, its editing status 
(read-only or write), editing mode (insert or overstrike), and direction (forward or 
reverse). 

8.15.1 Getting Buffer Information 

To display more information about the current buffer, enter the SHOW command. 
The information displayed includes whether the buffer has been modified, in 
addition to the following: 

• Buffer name 

• Names of the input, output, and buffer-change journal files 

• Current mode and direction 

• Number of lines 

• Margin and screen-width settings 

• Paragraph indent 

• WPS word wrap 

• Wrap indent 

• Tab stop 

If more than one buffer is active during an editing session, EVE prompts you to 
press the Do key to get information about other buffers. 


8-38 


Editing Text Files: Using EVE 
8.15 Using Buffers 


8.15.2 Deleting a Buffer 

To delete a buffer, enter the DELETE BUFFER command, and specify the name 
of the buffer you want to delete. If the buffer is empty or unmodified, EVE 
deletes it. If, however, the buffer has been modified, EVE prompts you for a 
choice. For example, the following command requests deletion of the modified 
buffer MYFILE.TXT: 

Command: DELETE BUFFER MYFILE.TXT 

That's a modified buffer. Type delete_only, write_first, or quit: 

The buffer name must be typed in full; no abbreviations are allowed. 

The following table lists the choices you can enter: 


Keyword 

Effect 

DELETE_ONLY 
WRITE_FI RST 

QUIT 

Deletes the specified buffer. 

Writes out (saves) the specified buffer, then deletes it. 

Default choice. The buffer is not deleted. 


If you are viewing a buffer that you want to delete, EVE replaces the buffer with 
the oldest buffer existing in the editing session. 


8.15.3 Changing Buffer Status 

Use the SET BUFFER command to change the editing status of the buffer; that 
is, whether the buffer can be modified and whether the buffer will be written to 
a file after you exit from EVE. You can specify one of the following keywords for 
each command: 


Keyword 

Effect 

MODIFIABLE 

Default setting. The buffer can be modified. Also restores the 
previous mode of the buffer (insert or overstrike). 

READ_ON LY 

The buffer is not saved (written out) on exiting, even if it has been 
modified (opposite of WRITE). Also sets the buffer to unmodifiable. 
However, you can set it to modifiable. 

UNMODIFIABLE 

The buffer cannot be modified. Also overrides the mode of the buffer 
(insert or overstrike). 

WRITE 

Default setting. The buffer is saved (written out) on exiting if it has 
been modified (opposite of READ_ONLY). If a buffer is read-only 
or unmodifiable, SET BUFFER WRITE makes it modifiable and 
restores its previous mode (insert or overstrike). 


By default, buffer status is set to MODIFIABLE and WRITE, letting you change 
the contents of a buffer and save the changed buffer in a file. 

To change the status of a buffer so that its contents cannot be inadvertently 
changed, set the buffer to READ_ONLY (which implies unmodifiable) with the 
following command: 

Command: SET BUFFER READ_0NLY 

To change the status of a buffer so it becomes a temporary storage area (a 
"scratchpad"), set the buffer to READ_ONLY and MODIFIABLE with the 
following commands: 
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Command: SET BUFFER READ_ONLY 
Command: SET BUFFER MODIFIABLE 

You then can edit the buffer, but it will not be saved when you exit from EVE. 

8.15.4 Displaying the Messages Buffer 

EVE uses the message window, which appears at the bottom of the screen, to 
communicate error and informational messages during an editing session. The 
message window displays the last message in the Messages buffer. 

You can display these messages with the BUFFER command. To display the 
contents of the Messages buffer, press Do and enter the command BUFFER 
MESSAGES. To return to the buffer you were editing, press Do and enter the 
BUFFER command followed by the name of the appropriate buffer. 

You can also enter the SFIOW BUFFERS command to display the buffers you 
have created and press the Select key to choose a buffer. 

8.15.5 Editing Multiple Buffers 

You can use several buffers if you want to edit more than one file or if you want 
temporary storage areas for manipulating blocks of text. 

You can use one of the following commands to create a new buffer: GET FILE or 
OPEN, OPEN SELECTED, or BUFFER. To create a new buffer with a file that 
already exists, enter the GET FILE (or OPEN) command and the name of the 
file you want to copy to the new buffer. You can use the asterisk (* ) wildcard 
character as a substitute for all or some of the characters in the file name and 
file type. You can use the percent sign (%) wildcard character as a substitute 
for one character in the file name and file type, and you can use the ellipsis ([...]) 
wildcard as a substitute for a directory specification. 

You can also use the OPEN SELECTED command to create a new buffer as 
follows: 

1. Put the cursor on the name of the file you want to open. 

2. Enter the OPEN SELECTED command. 

To put a specific buffer into the current EVE window, enter the BUFFER 
command and the name of the buffer you want to put in the current window. You 
cannot use wildcard characters in buffer names. The asterisk (*) and percent 
sign (%) are treated as literal characters in a buffer name. If the buffer you 
specify does not already exist, EVE creates a new buffer. 

If the specified file exists, EVE reads the contents of the file into a new buffer 
and displays the buffer in the current window. If there is more than one match 
for a file specification with a wildcard, EVE displays a list of choices in the 
$CHOICES$ buffer and prompts you to provide a more complete file specification. 
EVE will open the first file it matches if you use a search list or an ellipsis ([...]) 
wildcard. Otherwise, EVE creates an empty buffer and displays the buffer in the 
current window. 

To change the buffer in the current window, press the Do key, type BUFFER and 
the name of the buffer you want to display on the screen, and then press the 
Return key. If you forget a buffer name, enter the SHOW BUFFERS command 
to display the names of active buffers in your editing session and specify a buffer 
with the Select key. 
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8.15.6 Reading and Writing Files 

There are four ways to read a file into an EVE buffer: 

• I nvoke EVE with a file specification. 

• Enter the I NCLUDE FI LE command and the name of the file you want to 
include. EVE reads the entire contents of the file into the buffer just before 
the line where the cursor is located. Using the INCLUDE FILE command 
does not change the name of the buffer on the status line. 

• Enter the GET FILE or OPEN command and the name of the file you want 
to use. Either command creates a new buffer and reads the contents of an 
existing file into the buffer. The name of the buffer on the status line is the 
same as the file name you specify with the GET FILE or OPEN command 
(see Section 8.15.5). 

• Select or find a file name, then enter the OPEN SELECTED command. 

To write the contents of the current buffer to a file, enter the WRITE FILE 
command. You can include a file specification with the WRITE FILE command. 

If you do not include a file specification, EVE uses the input file specification 
to write the file. If you created the current buffer with the BUFFER or NEW 
command, EVE prompts you for a file specification to which it writes the file. 

The following example shows how to use the output file associated with the buffer 
to write out a buffer: 

Command: GET FILE RHYMES.DAT 


Command: WRITE FILE 

3 lines written to WORKDISK: [USER] RHYMES .DAT; 2 

8.15.7 Using Windows 

During an EVE editing session, the buffer you are editing is displayed on the 
screen in a window. A highlighted status line appears at the bottom of the 
window identifying the name, current editing mode, and current direction of the 
buffer. 

EVE lets you view more than one window on your terminal screen at the same 
time. For example, you can have two windows on the terminal screen to view and 
edit different sections of the same buffer. 

The following tables describe EVE keys and commands used to create and 
manipulate windows: 


Key or Key Sequence Function in a Window Environment 


GOLD Next Screen Puts the cursor in the next (or other) window. Same as the 

NEXT WINDOW command. For more information about 
GOLD key combinations, see Section A. 2. 3. 

GOLD Prev Screen Puts the cursor in the previous (or other) window. Same as 

the PREVIOUS Wl NDOW command. For more information 
about GOLD key combinations, see Section A. 2.3. 
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Command 

Function in a Window Environment 

DELETE WINDOW 

Deletes the current window, if you are using more than one 
wi ndow. 

ENLARGE WINDOW 

Enlarges the current window by a specified number of lines. 
For example, ENLARGE WINDOW 5 enlarges the window 
by five lines. The adjacent window shrinks accordingly. 

NEXT WINDOW 
or OTHER WINDOW 

Puts the cursor in the next (or other) window. 

ONE WINDOW 

Restores the current window as a single, large window. 

EVE deletes all other windows from the screen. The buffers 
associated with those windows are not deleted. 

PREVIOUS WINDOW 

Puts the cursor in the previous (or other) window. 

SET Wl DTH 

Sets the width of lines displayed on the screen. Specify 
width as a positive integer. By default, the screen width is 
your terminal setting (usually 80 columns). If the width is 
set greater than 80, EVE sets the terminal to 132-column 
mode for the current editing session. When you exit from 
EVE, the terminal is restored to the default setting. Setting 
the width changes the display of text in all windows. 

SHIFT LEFT 

Moves the current window to the left a specified number of 
columns. You can use the SHI FT LEFT command only to 
reverse the effect of the SHI FT RIGHT command. 

SHIFT RIGHT 

Moves the current window to the right a specified number 
of columns, so you can view columns of characters that do 
not currently appear on the terminal screen. 

SHRINK WINDOW 

Shrinks the current window by a specified number of lines. 
For example, SHRINK Wl NDOW 5 shrinks the window by 
five lines. The adjacent window expands accordingly. 

SPLIT WINDOW 

Splits the current window, forming two smaller windows. 
You can divide the window into more than two parts by 
specifying a number with the command. For example, 
SPLIT Wl NDOW 3 splits the window into three windows. 

TWO WINDOWS 

Same as the SP L 1 T Wl N DOW 2 command. 


8.15.8 Viewing One Buffer 

To view two sections of a file at the same time, use the SPLIT Wl NDOW 
command. EVE splits your screen and creates two identical windows. The cursor 
maintains its position in the buffer but appears only in the bottom window. The 
buffer name is the same in both status lines. 

Displaying two sections of a long file makes moving text within a file efficient. 
You can select and remove text from one part of the file and insert it into 
the other. To move the cursor from one window to the other, enter the NEXT 
WINDOW command. 

To remove the second window from the screen and expand the current window 
to occupy the whole editing area, press the Do key, enter the command ONE 
Wl NDOW, and press the Return key. 
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8.15.9 Editing Two Buffers 

The following steps describe how to edit two buffers containing different files: 

1. Create two windows on your screen by entering the SPLIT WINDOW 
command. EVE splits your screen and creates two windows. The cursor 
maintains its position in the buffer but appears only in the bottom window. 
The buffer name in each of the highlighted status lines is the same. 

2. Use the GET FILE, OPEN, or OPEN SELECTED command to put a second 
file in the current window. 

To display a buffer that you created earlier in the editing session in the 
current window, enter the BUFFER command and the name of the buffer you 
want to display. 

3. Your terminal screen now displays two different buffers. You can select and 
remove text from one buffer and insert it into the other buffer. To move the 
cursor from one window to the other, enter the command NEXT Wl N DOW. 

8.15.10 Creating a Subprocess 

You can create a subprocess to switch between an EVE editing session and DCL 
command level without terminating your editing session. To create a subprocess, 
enter the SPAWN command. EVE suspends the current editing session and 
connects your terminal to a new subprocess. The DCL prompt ($) appears on 
your terminal screen. 

The most common reasons to spawn a subprocess are to invoke the Mail utility 
and to run screen-oriented programs, although your subprocess can invoke any 
OpenVMS utility or execute any DCL command. 

To return to your editing session, log out of the subprocess by entering the DCL 
command LOGOUT. EVE resumes the editing session, and the cursor appears in 
the location it occupied before you spawned the subprocess. 

You can also supply a DCL command as a parameter to the SPAWN command to 
create a specific subprocess. The following example executes the Mail utility: 

[End of file] 

Buffer: MAIN | Write | Insert | Forward 

Command: SPAWN MAIL 

The prompt for the Mail utility (MAI L>) appears on the screen. When you exit 
from Mail, you are automatically logged out of the subprocess and EVE resumes 
the editing session. 

Rather than spawn a process to use DCL, you can spawn a process for an EVE 
editing session and then attach to the parent DCL process to use DCL commands 
and utilities. 

First, create a subprocess using the DCL command SPAWN. For example: 

$ SPAWN 

%DCL-S-SPAWNED, process SMITH_1 spawned 
%DCL-S-ATTACHED, terminal now attached to process SMITH_1 

The SPAWN command creates a subprocess (displayed by the SHOW PROCESS 
command as SMITH_1). At the subprocess level, invoke EVE and conduct the 
editing session. 
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When you want to return to the DCL command level, use the EVE command 
ATTACH to return to the parent process. (SHOW PROCESS displays the process 
SMITH.) 

[End of file] 

Buffer: MAIN | Write | Insert | Forward 

Command: ATTACH SMITH 

To resume your editing session, reconnect to the editing subprocess by using the 
DCL command ATTACH with the process name of the subprocess (SMITH_1). 
EVE resumes the editing session and the cursor appears in the location it 
occupied before you attached to the parent process. For example: 

$ ATTACH SMITH_1 

8.15.11 Running File Backups 

EVE file backups are disabled and cannot be enabled because the OpenVMS file 
system provides version numbers; therefore, no EVE mechanism is needed. 
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Although the default text editor on the OpenVMS operating system is EVE, you 
may also wish to use the EDT editor. EDT is an interactive text editor with 
which you can create a new file, insert text into it, and modify that text. You can 
also edit text in existing files with EDT. 

EDT provides both line editing and keypad editing. In line editing, you type 
the editing command and the range of text you want the command to affect. I n 
keypad editing, you move the cursor directly to the text you want to change and 
press keypad keys to enter the editing commands. 

One way to use EDT is to use the keypad as the primary editing mode in 
combination with various line-editing commands. You can also redefine certain 
keypad and control keys to perform editing functions not available in keypad 
mode. This is called nokeypad editing. Nokeypad commands are the basis for 
keypad mode key definitions and consist of English words and abbreviations. You 
can use nokeypad mode commands to define keys. 

This chapter describes: 

• Invoking and ending an EDT session 

• Entering EDT commands 

• Getting help in EDT 

• Changing editing modes 

• Recovering from interruptions 

For more detailed information on using EDT, seeth e OpenVMS EDT Rdference 
Manual or refer to online help. 

9.1 Beginning an EDT Editing Session 

To invoke EDT, enter the DCL command EDIT/EDT followed by the name of the 
file you want to edit. For example, to edit a file named MEMO.TXT, enter the 
following command line: 

$ EDIT/EDT MEMO.TXT 

Once the weather turns cold, mice may find a crack in your 
foundation and enter your house. They're looking for food and 
shelter from the harsh weather ahead. 

[EOB] 

The first few lines of the latest version of the file appear on the screen. The 
cursor is positioned at the top of the screen, and EDT is ready to receive a 
keypad-editing command. 
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9.1 Beginning an EDT Editing Session 

When you edit a file that already exists (for example, if you created the file 
during a previous session), EDT saves the existing versions and places a copy of 
the latest version in your buffer. A buffer is the temporary storage area in which 
you edit text. The existing versions of the file remain unchanged. 

If you invoke EDT to create a file, the following message appears: 

$ EDIT/EDT NEWFILE.TXT 

Input file does not exist 
[EOB] 

~k 

Only the EDT message and the end-of-buffer symbol ([EOB]) appear on the 
screen, and EDT is ready to receive keypad-editing commands. See Section 9.2 
for a description of EDT line commands. 

In the previous examples, you enter EDT in keypad (change) mode because a 
startup command file (SYS$LOGIN:EDTINI.EDT) containing the SET MODE 
CHANGE command has been executed. If this command is not executed in an 
EDT startup command file, you enter EDT in line mode. Enter the CHANGE 
command at the asterisk (* ) prompt to change to keypad mode. 

For information on creating a startup command file, see the OpenVMS EDT 
Reference Manual . 

9.2 Entering EDT Line Commands 

EDT prompts for line-editing commands with an asterisk (*). Line-editing 
commands usually operate on a range of one or more lines of text that you specify 
as a parameter for the command. For example, to display an entire file on your 
screen, enter the TYPE command and specify WHOLE as the parameter as 
follows: 

*TYPE WHOLE 

You can abbreviate EDT line-editing commands. For clarity, the examples in this 
chapter show complete line-editing commands. 

9.2.1 Using Line Numbers 

To help you locate and edit text, EDT assigns line numbers. These line numbers 
are not part of the text and are not kept when you end an editing session. 

Table 9-1 describes how you can specify one line or a range of lines during an 
EDT session. To display all the lines of an existing file, enter theTYPE WHOLE 
command. For example: 

* TYPE WHOLE 

1 
2 

3 

4 

5 

[EOB] 

* 

When you insert new text, EDT numbers the lines using decimal numbers. For 
example, if you add a line of text between lines 13 and 14, it is numbered 13.1. To 
avoid confusion when working with decimal numbers, enter the RESEQUENCE 
command. The RESEQUENCE command renumbers all the lines from the cursor 
to the end of the buffer in increments of one. 


oneoneoneoneoneoneone 
twotwotwotwotwo 
threethreethree 
four four four four 
fivefivefivefive 
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Note that the EDT line-editing command SET NUMBERS (the default) must be 
in effect for line numbers to be displayed in EDT line editing. 

9.2.2 Specifying a Range of Lines 

Some EDT line-mode commands can affect a range of lines. For example, the 
INSERT command will create a new line of text in your buffer; to insert a new 
line of text at the beginning of your buffer, enter the command INSERT BEGI N . 
Table 9-1 describes the different ranges you can specify when you edit a file in 
line mode. 


Table 9-1 EDT Line-Mode Command Ranges 


Range Type 


Description 

period (.) 


Current line 

number 


EDT line number 

' string' 


Next line containing the quoted string 

BEGIN 


First line of the buffer 

END 


After the last line in the buffer ([EOB]) 

LAST 


Last line EDT was at in the previous buffer 

WHOLE 


Entire buffer 

BEFORE 


All lines in the buffer before the current line 

REST 


All lines in the buffer starting with the current line and ending with 
the last line 

Table 9-2 lists symbols and words that you can combine with the range types 
listed in Table 9-1. 

Table 9-2 

EDT Command-Line Symbols for Specifying Ranges 

Symbol or Word 

Description 

, or AND 


Used to join noncontiguous ranges in a list; only single lines 
can bejoined in this way 

: or THRU 


Indicates a group of lines starting with the first range 
specifier and ending with the second 

n 


1 ndicates the number of lines from the current line 

#n or FOR n 

Indicates the next n number of lines 

+ "string" or 

"n" 

1 ndicates that string or n refers to a line or lines after the 
current line 

- "string" or 

"n" 

1 ndicates that string or n refers to a line or lines before the 
current line 

ALL "string' 

’ or "n" 

1 ndicates that the command applies to all lines containing 
string 


9.3 Entering EDT Keypad Commands 

While line editing allows you to manipulate large portions of text easily, keypad 
editing provides easy manipulation of small units of text. EDT keypad commands 
enable you to find, insert, delete, substitute, and move text in a file. The cursor 
can be moved through a file in a variety of ways. The position of the cursor in a 
file determines how text will be affected by EDT commands. 
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In keypad editing, the screen displays editing changes as you make them. You 
type text from the main keyboard and enter keypad-editing commands from the 
numeric keypad. To display a diagram of the keypad keys, press PF2 while in 
keypad mode. To initiate keypad editing, you must first enter the line-editing 
command CHANGE or have SET MODE CHANGE in your EDT startup file. See 
Section 9.7.2 for information on the CHANGE command. 

See the description of EDT line-editing commands in Table 9-3 for more 
information about keypad editing keys. 

Each key in the keypad performs at least one editing command; most perform 
two. Pressing a key invokes the primary function. To invoke the alternate 
function of a key, press the GOLD key (labeled PF1) first, then press the desired 
key. I n the examples that follow, a small diagram of the keypad highlights 
the key or key sequences that perform the command being described. The text 
associated with the keypad illustrates the effect of that editing command. 

For example, keypad key 1 (KP1) performs both the WORD and the CHNGCASE 
functions. To enter the WORD command, press KP1. The cursor moves to the 
beginning of the next word. 

WORD 


□□□ 


□□□ 


□□□ 





Once the weather turns cold, mice may 

find a crack in your foundation and enter your house. They're 
looking for food and shelter from the harsh weather ahead. 

[EOB] 

To enter the CHNGCASE command, press the GOLD key first and then 
CHNGCASE. The character at the cursor (or the characters highlighted with the 
Select key) changes from lowercase to uppercase or from uppercase to lowercase. 


CHNGCASE 




□□□ 


□□□ 





Once The weather turns cold, mice may 

find a crack in your foundation and enter your house. They're 
looking for food and shelter from the harsh weather ahead. 

[EOB] 

The "T" in the word 'The" is now capitalized. 

The supplemental editing keys on the keypad perform the same functions as some 
of the EDT keypad keys. See the description of EDT line-editing commands in 
Table 9-3 for more information about these supplemental editing keys. 
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9.4 Canceling EDT Commands 

Use Ctrl/C to cancel the currently executing EDT command without affecting 
previous edits. For example, to stop the display of a long file, press Ctrl/C. 

*TYPE WHOLE 


[CtriTcl 

Cancel 

Press return to continue 

| Return | 

Aborted by CTRL/C 

9.5 Using Online Help in EDT 

In keypad mode, you can display a diagram of the keypad keys by pressing PF2. 
On LK201-series keyboards, you can also use the H el p key on the supplemental 
editing keypad. To display information about a particular keypad command, first 
press the H el p key and then press the keypad key. 

To request help in EDT while in line mode, enter the FIELP command at the 
asterisk (*) prompt and press Return. To display information about a particular 
command, type FIELP followed by the name of the command. EDT displays 
information about the command and lists related topics. For example, to request 
help on the COPY command, enter the following command line: 

*HELP COPY [Return] 

If you are in nokeypad mode and want to get help information about nokeypad 
commands, enter HELP CHANGE at the asterisk (*) prompt. 

9.6 Ending an EDT Editing Session 

To terminate an EDT session, press Ctrl/Z. This puts you into line-editing mode. 
You can type EXIT or QUIT at the asterisk (*) prompt. EXIT saves your edits in 
a new version of the file; QUIT terminates the editing session and does not save 
your edits. 

The existing versions of a file remain unchanged regardless of how you end the 
editing session. 

9.6.1 Saving Your Edits When You Exit from EDT 

By default, the EXIT command creates an output file with the same file name 
and file type as the input file but with the version number incremented by 1. For 
example, if you enter the EXIT command after editing a file named MEMO.TXT;3, 
EDT creates a higher version named MEMO.TXT;4 as follows: 

*EXIT 

DISKI: [USER] MEMO. TXT; 4 2 lines 

S 

To override the default output file name, enter the EXIT command with a new file 
specification as the parameter. For example, if you end the same editing session 
with the command EXIT MICE.TXT, EDT names the output file MICE. TXT; 1, 
provided nootherfilenamedMICE.TXT exists. lfafilenamedMICE.TXT exists, 
EDT names the output file MICE.TXT; version-number, where version-number is 
one greater than the highest version number of an existing MICE.TXT file. Note 
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that if a file is given the same file name as an existing file, the two files will have 
the same file name and file type, but different version numbers and content. 

9.6.2 Ending the EDT Session Without Saving Your Edits 

To terminate EDT without saving your edits, use the line-editing command QUIT. 
All edits you have made to the text are ignored, and no output file is created. 

*QUIT 

$ 

The QUIT command is a useful way to terminate EDT when you have opened a 
file by mistake. No new file version is created. 

9.7 Changing Editing Modes 

You can switch back and forth between line and keypad editing. You can also 
enter line-editing commands from keypad mode. If find yourself frequently 
returning to line mode to enter EDT commands, you might find it easier to work 
in line mode. For example, if you are examining a file on a line-by-line basis, 
using line numbers as reference points, line-mode editing is more appropriate. 

In contrast, if you need to examine, cut, and paste large chunks of text between 
nonadjacent areas within a file or between two files, keypad editing might be 
faster. 

9.7.1 Changing from Keypad to Line Editing 

To change from keypad editing to line editing, press Ctrl/Z. When you see the 
asterisk (* ) prompt at the bottom of your screen, enter a line-editing command at 
the prompt. For example: 

Once the weather turns cold, mice may find a crack in your 
foundation and enter your house. They're looking for food and 
shelter from the harsh weather ahead. 

[EOB] 

| Ctrl/Z | 


* INSERT 

9.7.2 Changing from Line to Keypad Editing 

To change from line editing to keypad editing, enter the CFIANGE command: 

* CHANGE 

The first 22 lines of the file display on your screen. If the file has fewer than 22 
lines, the [EOB] symbol appears below the last line of the file. 

9.7.3 Entering Line-Editing Commands from Keypad Mode 

The keypad COMMAND function allows you to enter line-editing commands 
without leaving keypad mode. First, enter the COMMAND function by pressing 
the GOLD key (PF1) and then the COMMAND key (KP7). 

COMMAND 






□□□ 


□□□ 
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EDT displays the Command: prompt. At the prompt, enter a line-editing 
command. For example: 

Once the weather turns cold, mice may find a crack in your 
foundation and enter your house. They're looking for food and 
shelter from the harsh weather ahead. 

[EOB] 

Command: SET QUIET 

This example enters the line-editing command SET QUI ET, which suppresses the 
sound made when EDT issues an error message. To execute the command, press 
the Enter key. (If you press Return by mistake, y 'M appears; delete the y 'M by 
pressing the Delete key on the main keyboard and press Enter.) 

ENTER 

□ □□□ 

□ □□□ 

□ □□□ 

□ □□ 


9.8 Recovering from Interruptions 

You can recover from interruptions to your editing session in the following ways: 

• Deleting extraneous characters 

Pressing Ctrl/W removes extraneous characters (such as a broadcast message 
or a message indicating that you have received electronic mail) from the 
screen and restores the previous display. Use Ctrl/W to ensure that the 
cursor is in the correct position. 

• Resuming an interrupted editing session 

The DCL command CONTINUE resumes an editing session that was 
interrupted by pressing Ctrl/Y, as long as only built-in DCL commands 
were entered after pressing Ctrl/Y. For example, you could press Ctrl/Y, 
enter the command SFIOWTIME, and return to your editing session with 
the CONTINUE command. You enter the SHOW TIME and CONTINUE 
commands at the DCL prompt. 

After you enter the CONTI NUE command, press Ctrl/W to refresh the screen 
display. EDT redisplays the text of your editing session. 

• Recovering a lost session 

By default, EDT keeps a journal file with the same file name as the input 
file and a file type .J OU . If the editing session ends without interruption, the 
journal file is deleted when you terminate the session. If the editing session is 
aborted (for example, during a system failure, in response to pressing Ctrl/Y, 
or entering the QUIT/SAVE command), you can recover your edits with the 
exception of those commands entered just prior to the interruption. Enter 
the same command line you used to begin the editing session, adding the 
/RECOVER qualifier. For example: 

$ EDIT/RECOVER MICE.TXT 

EDT will reproduce the editing session, reading the commands from the 
journal file and executing them on the screen. 
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9.9 Summary of EDT Commands 

In keypad mode, you can manipulate the cursor with commands that move 
it unit-by-unit through the text or with commands that move it directly to 
a particular location. Table 9-3 lists each EDT command and gives a brief 
description of its function. The table also lists nokeypad commands, which you 
can use to define keys and to perform editing functions not available in keypad 
mode. 


Table 9-3 Summary of EDT Commands 


Keypad 

Mode 

Line Mode 

Nokeypad 

Mode 

Description 

Changing Editing Modes 

COMMAND 


EXT 

(Extend) 

Enables you to enter a line-mode command 
while EDT is still in keypad or nokeypad mode. 

Ctrl/Z 

CHANGE 

EX 

Transfers your editing session from one mode 
(line, keypad, or nokeypad) to another. 


SET MODE 

SHOW MODE 


Establishes the initial mode of the EDT session 
when used in a startup command file. SHOW 
MODE indicates which SET MODE command 
was most recently issued. 

Manipulating the Cursor 

BACKSPACE 


BL 

Moves the cursor to the beginning of the current 
line. 

BOTTOM 

TYPE END 

ER 

Moves the cursor to the end of the buffer, after 
the last character position in the buffer. 

CHAR 


C 

Moves the cursor one character in the current 
direction (forward or backward, depending on 
whether ADVANCE or BACKUP is in effect). 

1 


1 

Moves the cursor down one line toward the 
bottom of the buffer, regardless of whether 
ADVANCE or BACKUP is in effect. 

EOL 


EL 

Moves the cursor to the end of the current 
line if the direction is forward. If the current 
direction is backward, the cursor moves to the 
end of the previous line. 




Moves the cursor one character to the left, 
regardless of whether ADVANCE or BACKUP 
is in effect. 



"move" 

Moves the cursor within the current buffer. 

LINE 


L 

Moves the cursor to the beginning of the 
next line if the direction is forward or to the 
beginning of the current line if the direction 
is backward. If the direction is backward, 
pressing LINE again moves the cursor to the 
beginning of the previous line. 



KS 

Modifies the position of the cursor at the 
completion of the PASTE command. 


(continued on next page) 
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Table 9- 

-3 (Cont.) Summary of EDT Commands 


Keypad 

Mode 

Line Mode 

Nokeypad 

Mode 

Description 

Manipulating the Cursor 

PAGE 


PAGE 

PAGETOP 

Moves the cursor to the right of the next page 
marker or to the next form-feed character. If 
you have no page markers (defined with the 
SET ENTITY PAGE command), the PAGE 
entity is the whole buffer. 



TOP 

M oves the cursor to the top of the screen. 

— > 


— > 

Moves the cursor one character to the right, 
regardless of of whether ADVANCE or 

BACKUP is in effect. 

SECT 


16L. 

Moves the cursor one section (16 lines) 
toward the end or the beginning of the buffer, 
depending on whether ADVANCE or BACKUP 
is in effect. 


SET CURSOR 

SHOW CURSOR 


Controls scrolling of the screen relative to the 
cursor position. This command has no effect if 
you are editing in line mode. SHOW CURSOR 
displays values set by the SET CURSOR 
command. 

TOP 


BR 

Moves the cursor to the first character at the 
beginning of the buffer. 

T 


T 

Moves the cursor up one line toward the top of 
the buffer regardless of of whether ADVANCE 
or BACKUP is in effect. 

WORD 


W 

Moves the cursor to the beginning of the 
next word in the current direction (forward 
or backward, depending on whether ADVANCE 
or BACKUP is in effect). 

Inserting Text 

Ctrl/L 


~L. 

1 nserts a form-feed character ( <F F>) into your 
text. 

Ctrl/M 


''M. 

1 nserts a carriage-return character (<CR>) into 
your text. 

Ctrl/R 

Ctrl/R 

REF 

Clears and redraws the screen display (in 
keypad mode) or line (in line mode), eliminating 
any extraneous characters or messages. 

The current text you are editing remains 
unchanged. In keypad mode, Ctrl/R is identical 
to Ctrl/W. 

Ctrl/W 


REF 

See Ctrl/R. 


Ctrl/Z 

Ctrl/Z 

Completes the insert operation and returns 

EDT to the command state. Used with the 
INSERT (nokeypad 1) and REPLACE (nokeypad 
R) commands. 




(continued on next page) 
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Table 9-3 (Cont.) Summary of EDT Commands 

Keypad 

Mode 

Line Mode 

Nokeypad 

Mode 

Description 

Inserting Text 

FILL 

(VT100) 

Ctrl/F 

(VT52) 

FILL 

FILL 

FILLSR 

Takes a select range of lines and reorganizes 
the text so that the maximum number of whole 
words can fit within the current line width. 1 n 
line mode, fills a selected range of lines. 


INCLUDE 


Copies external files into the EDT text buffer. 

In line mode, EDT displays an asterisk (*) 
prompt when the INCLUDE command finishes 
copying the file. In keypad or nokeypad mode, 
the included text appears on the screen. 

OPEN LINE 

INSERT 

1 | Return | 

1 nserts a line terminator in the text you are 
editing at the current cursor position and 
makes the line terminator the new cursor 
character. 


INSERT 

1 

Adds text to the current or specified buffer. 

SPECINS 


ASC (ASCII) 
Circumflex 

r) 

Enables you to insert any character from the 
DEC Multinational character set into your text, 
using the character's decimal equivalent value 
(see Appendix B). The circumflex ( ~) works 
only for characters with decimal values 0 to 31. 

Deleting and Restoring Text 

Ctrl/U 


DBL 

Deletes everything from the character to the 
left of the cursor to the beginning of the line. 


DELETE 

D 

Deletes a line or group of lines, depending on 
the range that you specify. If you do not specify 
a buffer or a range, EDT deletes the current 
line. If you specify a buffer but not a range, 
EDT moves to that buffer and deletes its entire 
contents. 

DEL C 

DELETE 

DC 

Deletes the character on which the cursor is 
positioned. 



D-C 

Deletes the character to the left of the cursor. 



D-tC 

Deletes the character to the right of the cursor. 

DEL EOL 

DELETE 

DEL 

Deletes everything on a line from the current 
cursor position up to, but not including, the line 
terminator. 

DEL L 

DELETE 

D+NL 

Deletes everything on a line from the current 
cursor position up to and including the line 
terminator. 

DEL W 

DELETE 

DEW 

Deletes words or parts of words. 

LINEFEED 


DBW 

Deletes the word or characters in a word to 
the left of the cursor up to the beginning of the 
previous word. 




(continued on next page) 
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Table 9-3 (Cont.) Summary of EDT Commands 


Keypad 

Mode 

Line Mode 

Nokeypad 

Mode 

Description 

Deleting and Restoring Text 

REPLACE 

REPLACE 

R (Replace) 

1 n keypad mode, deletes text in the select range 
and replaces it with the contents of the PASTE 
buffer. In line and nokeypad mode, deletes the 
lines specified by range from the current or 
specified buffer and replaces the deleted lines 
with text that you enter at the terminal. 

UND C 


UNDC 

1 nserts the current contents of the delete 
character buffer into text to the left of the 
cursor. 

UND L 


UNDL 

1 nserts the current contents of the delete line 
buffer into text to the left of the cursor. 

UND W 


UNDW 

1 nserts the current contents of the delete word 
buffer into text to the left of the cursor. 

Locating Text 

ADVANCE 


ADV 

Sets the direction for subsequent editing work 
to forward (to the right of the cursor and down 
toward the end of the buffer). 

BACKUP 


BACK 

Sets the direction for subsequent editing work 
to backward (to the left of the cursor and 
toward the beginning of the buffer). 



CLSS 

Clears the text string currently in the search 
buffer. 

FIND 

FIND 

"string" 

Searches for specified text. 

FNDNXT 

FIND "" 

mi 

Searches for the next occurrence of a string 
defined by the FIND command. 

RESET 


RESET 

Cancels the active select range, sets the 
direction to advance, and sets EDT to the 
DMOV (default move) state. 



DESEL 

Cancels the active select range. 



TGSEL 

Combines the SEL and DESEL commands. 
When there is an active select range, the 
TGSEL command cancels it, performing the 
same function as the DESEL command. When 
there is no active select range, TGSEL initiates 
the process of creating a select range, just as 
the SEL command does. 

SELECT 


SEL 

Sets up a select range for use with keypad 
functions such as APPEND, CHNGCASE, CUT, 
FILL, REPLACE, SUBS, and Ctrl/T. 


(continued on next page) 
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Table 9-3 (Cont.) Summary of EDT Commands 


Keypad 

Mode 

Line Mode 

Nokeypad 

Mode 

Description 

Locating Text 



SSEL 

Finds a string and designates it as a select 
range. 


SET SEARCH 

SHOW SEARCH 


Determines how EDT locates strings during 
your editing sessions. SHOW SEARCH 
indicates the search parameters EDT uses 
to locate strings in text. 

Substituting Text 

SUBS 

SUBSTITUTE 

S 

In keypad mode, replaces the current search 
string with the contents of the PASTE buffer. 

In line and nokeypad mode, replaces one string 
with another throughout the specified range. 


SUBSTITUTE NEXT 

SN 

Searches for the next occurrence of a string and 
replaces it with another string. This command 
uses strings that have been stored in the search 
buffer and in the substitute buffer. 

Moving Text 

APPEND 


APPEND 

Deletes the select range (keypad mode) or 
specified entity (nokeypad mode) from the 
current buffer and adds it to the end of either 
the PASTE buffer (the default) or the specified 
buffer. 


COPY 


Copies the specified text to the specified 
location. You can copy a range of text from 
one location to another within the same buffer, 
or you can copy to and from different buffers, 
creating new buffers as appropriate. No text 
is deleted. The /DUPLICATE qualifier enables 
you to copy the specified text n times. 

CUT 


CUT 

1 n keypad mode, removes the active select 
range from the current buffer and stores it in 
the PASTE buffer. In nokeypad mode, removes 
the specified entity from the text buffer and 
stores it in another specified buffer. 

CUT + 
PASTE 

MOVE 

CUT + 
PASTE 

Moves lines from one location to another 
within the current buffer or from one buffer 
to another. The lines are deleted from their 
original position and are inserted at the new 
location. 

PASTE 

COPY, MOVE 

PASTE 

Copies or moves text within a buffer. In keypad 


mode, PASTE copies the PASTE buffer contents 
into the current buffer. In nokeypad mode, 
PASTE copies the contents of any buffer into 
the current buffer. 


(continued on next page) 


9-12 


Editing Text Files: Using EDT 
9.9 Summary of EDT Commands 


Table 9-3 (Cont.) Summary of EDT Commands 


Keypad 

Mode 

Line Mode 

Nokeypad 

Mode 

Description 

Indenting Text 

Ctrl/A 


TC (Tab 
Compute) 

Establishes a tab position and resets the 
indentation level. The indentation level is 
the number of columns, starting at the left of 
the screen, that you want to leave blank before 
beginning a line of text. To use this command, 
the current cursor position must be a multiple 
of the SET TAB value. 

Ctrl/D 


TD (Tab 
Decrement) 

Decreases the current indentation level count 
by one setting. The indentation level count is 
generally set by the Ctrl/A or TC (Tab Compute) 
command. 

Ctrl/E 


Tl (Tab 
Increment) 

1 ncreases the current indentation level count 
by one setting. The indentation level count is 
generally set by the Ctrl/A or TC (Tab Compute) 
command. 

Ctrl/T 

TAB ADJ UST 

TADJ (Tab 
Adjust) 

Uses the value established by the line-mode 
SET TAB command to indent lines of text in a 
select range. Requires SET TAB to be in effect. 


SET TAB 

SHOW TAB 


Establishes the SET TAB value for the various 
tabbing functions (tab compute, tab adjust, 
tab increment, and tab decrement). SHOW 

TAB indicates the SET TAB value and the tab 
indentation level count. 



SHL (Shift 
Left) 

Moves the entire buffer text eight characters 
(one tab stop) to the left. 



SHR (Shift 
Right) 

Moves the entire buffer text eight characters 
(one tab stop) to the right. 

TAB, Ctrl/I 


TAB 

Moves text to the right, regardless of whether 
ADVANCE or BACKUP are in effect. The 
number of column positions that the text moves 
depends on the cursor position, the value set by 
the SET TAB command (if one is in effect), and 
the indentation level count (if one is in effect). 

Changing the Case of Text 

CHNGCASE 


CHGC 

Changes the case of letters in your text. 
Uppercase letters become lowercase; lowercase 
letters become uppercase. 



CHGL 

Changes all uppercase letters within the 
specified entity to be lowercase. Letters that 
are already lowercase remain unchanged. 



CHGU 

Changes all lowercase letters within the 
specified entity to be uppercase. Letters that 
are already uppercase remain unchanged. 



DLWC 

Changes uppercase letters to lowercase 


wherever the cursor is moved. 

(continued on next page) 
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Table 9-3 (Cont.) Summary of EDT Commands 


Keypad 

Mode 

Line Mode 

Nokeypad 

Mode 

Description 

Changing the Case of Text 



DU PC 

Changes lowercase letters to uppercase 
wherever the cursor is moved. 



DMOV 

Returns the editing session to the default state 
after you use either DLWC (default lowercase) 
or DU PC (default uppercase). 


SET CASE 

SHOW CASE 


Uses flags to distinguish uppercase and 
lowercase letters at a single-case terminal. 
SHOW CASE indicates which case (upper, 
lower, or none) has been established by the SET 
CASE command. 

Using Multiple Buffers 


CLEAR 


Deletes the contents of the specified buffer. 


SHOW BUFFER 


Lists all accessible buffers currently in your 
EDT session. 

Defining Keys 



BELL 

Causes the terminal bell to sound when a 
command is processed. Used primarily in 
keypad key definitions. 

Ctrl/K 

DEFINE KEY 

DEFK 

Defines or redefines function keys used in 
keypad editing. Key definitions are based on 
nokeypad commands. 1 n keypad mode, Ctrl/K 
starts the key definition process. In nokeypad 
mode, you can define a key sequence other than 
Ctrl/K to handle the key definition process. 


SHOW KEY 


Displays the definition of any keys that have 
keypad editing functions. 


SET [NO]KEYPAD 
SHOW KEYPAD 


Determines which screen editing mode (keypad 
or nokeypad) EDT accesses from line mode 
when you enter the CHANGE command. 

SHOW KEYPAD indicates which mode is in 
effect. 

Controlling Screen and Terminal Settings 

| Return | 



Adds a line terminator to the left of the current 
cursor position in the text you are editing. 


SET 

[NOJAUTORE PEAT 
SHOW AUTOREPEAT 


Prevents keypad keys (including arrow keys) 
from repeating faster than EDT can update 
the screen. SHOW AUTOREPEAT indicates 
whether autorepeat is in effect. 


SET LINES 

SHOW LINES 


Limits the number of lines that EDT displays 
on the terminal screen at onetime. SHOW 


LINES displays the line limit. 


(continued on next page) 
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Table 9-3 (Cont.) Summary of EDT Commands 

Keypad Nokeypad 

Mode Line Mode Mode Description 


Controlling Screen and Terminal Settings 


SET [NO]NUMBERS 
SHOW NUMBERS 


SET PARAGRAPH 
[NO]WPS 

SHOW PARAGRAPH 


SET [NO]QUI ET 
SHOW QUIET 


SET [NO]RE PEAT 
SHOW REPEAT 


SET SCREEN 
SHOW SCREEN 


SET TERMINAL 
SHOW TERMINAL 


SET TEXT 
SHOW TEXT 


SET [NO]TRUNCATE 
SHOW TRUNCATE 


SET WORD 
[NO]DELI MITER 
SHOW WORD 


SET [NO]WRAP 
SHOW WRAP 


Determines whether EDT displays line numbers 
during line-mode editing. SHOW NUMBERS 
displays the current setting. 

Sets paragraph default boundary limits. 

SHOW PARAGRAPH indicates whether SET 
PARAGRAPH WPS or SET PARAGRAPH 
NOWPS is in effect. 

Silences the terminal bell that ordinarily 
sounds whenever EDT displays an error 
message during a screen-mode editing session. 
SHOW QUIET indicates whether the bell has 
been turned off. 

Disallows use of the GOLD key repeat feature, 
which allows you to repeat functions in keypad 
mode, and the SPECI NS keypad function. 
SHOW REPEAT indicates whether SET 
REPEAT or SET NOREPEAT is in effect. 

Changes the maximum number of characters 
displayed on each screen line. SHOW SCREEN 
displays the current screen width setting. 

Corrects or changes terminal settings to match 
the type of terminal you are using. SHOW 
TERMINAL displays the terminal settings that 
are currently in effect for your editing session. 

Personalizes the form-feed character ( <FF>) 
or the end-of-buffer ( [E OB ] ) mark. SHOW 
TEXT indicates what text is displayed for the 
form-feed character or the end-of-buffer mark. 

Causes lines longer than the current screen 
width to wrap onto subsequent lines when 
you are working in screen mode. (In line 
mode, EDT always wraps long lines.) SET 
TRUNCATE does not take word boundaries 
into consideration; enter SET WRAP to break 
lines at word boundaries. SHOW TRUNCATE 
indicates whether SET TRUNCATE is in effect. 

Determines how word entity boundaries 
are interpreted by EDT. By default, word 
delimiters are treated as separate words (SET 
WORD DELIMITER). SHOW WORD indicates 
whether SET WORD NODELIMITER is in 
effect. 

Causes lines of text to wrap when new text 
is inserted into a buffer in keypad mode. The 
SET WRAP command also determines the line 
length for the FILL command. SHOW WRAP 
indicates whether the SET WRAP command is 
in effect and, if so, what the SET WRAP value 
is. 


(continued on next page) 
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Table 9-3 (Cont.) Summary of EDT Commands 


Keypad 

Mode 

Line Mode 

Nokeypad 

Mode 

Description 

Processing EDT Commands 

Ctrl/C 

Ctrl/C 

Ctrl/C 

Interrupts certain operations (such as a 
search through a long file) before EDT finishes 
processing them. 

Do (LK201 
only) 

| Return | 

Period (.) 

Processes searches and line editing commands. 

Enter 

| Return | 

| Return | 

Processes searches, line editing commands, and 




key definitions. 


SET ENTITY 

SHOW ENTITY 


Defines the delimiters that mark the word, 
sentence, paragraph, and page boundaries for 
commands and functions. SHOW ENTITY lists 
the current delimiters. 


SET COMMAND 
SHOW COMMAND 


Processes additional startup command files at 
the beginning of your EDT session. SHOW 
COMMAND displays the name of the active 
startup command file. These commands are 
valid only in an EDT startup command file. 


SET [NOJVERIFY 
SHOW VERIFY 


Displays the commands in a startup command 
file or EDT macro as the commands are 
processed. SHOW VERIFY indicates whether 
SET VERIFY is in effect. 

Miscellaneous Commands 



DATE 

1 nserts the current date into your text. 


DEFINE MACRO 


Creates new line-mode commands for the 
duration of your editing session. 


EXIT 


Creates an external file, copies the contents of 
the MAIN buffer into that file, and ends the 
editing session. 

GOLD 



Performs various editing functions when used 
with other keypad and keyboard keys. 

Help 

Help 

Help 

In keypad and line modes, accesses the EDT 
Help utility. In nokeypad mode, defines a 
different key or key sequence in keypad mode 
to carry out the keypad Help function. 


PRINT 


Copies the specified range of lines or specified 
buffer to an external file in a specified directory. 
EDT adds a form feed and two blank lines for 
every 60 lines it copies. The EDT line numbers 
become part of the text in the external file. 


QUIT 

QUIT 

Ends the session without copying text to an 
external file. 


RESEQUENCE 


Assigns new EDT line numbers to the lines of 
the current or specified buffer. 


SHOW FILES 


Displays the current input file and output file 


for your EDT session. 

(continued on next page) 
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Table 9-3 (Cont.) Summary of EDT Commands 


Keypad 

Mode 

Line Mode 

Nokeypad 

Mode 

Description 

Miscellaneous Commands 


SET [NO]FNF 

SHOW FNF 


Suppresses the message that appears when you 
use EDT to create a new file (FNF stands for 
File Not Found). SHOW FNF indicates whether 
SET FNF or SET NOFNF is in effect. These 
commands are used only in startup command 
files. 


SET HELP 

SHOW HELP 


Enables you to access different help files for 
your EDT session. SHOW HELP displays the 
name of the help file currently available for 
your editing session. 


SET [NO]SUMMARY 
SHOW SUMMARY 


Suppresses summary information displayed 
when you enter the EXIT or WRITE commands. 
By default, E DT displays the complete file 
specification and number of lines in the file that 
EDT has created as a result of entering the 
EXIT or WRITE command. SHOW SUMMARY 
indicates whether the SET SUMMARY 
command is in effect. 


SHOW VERSION 


Displays the version of EDT that is being used 
by your operating system. 


TYPE 


Displays lines of text at your terminal. 


WRITE 


Copies text from an E DT buffer to an external 
file. 



XLATE 

Passes information back to the calling program. 
You can enter this command when EDT has 
been called by a running program. 
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DIGITAL Standard Runoff (DSR): Formatting 

Text Files 


DIGITAL Standard Runoff (DSR) is a text-formatting facility. By inserting DSR 
commands, control characters, and other special identifiers within a text file, 
you can use DSR to determine the size of pages, create uneven or justified right 
margins, place space between lines, and form lists. You can also direct DSR to 
provide title pages, footnotes, tables of contents, indexes, and appendixes. 

The steps for formatting a file with DSR are as follows: 

1. Create the source file with EDT, EVE, or another text editor. By default, the 
DSR source file has the file type .RNO. 

2. Enter DSR commands, flags, and control characters within the source file to 
indicate how the file is to be formatted. DSR flags are special characters that 
you insert in text to specify emphasis of text, case of characters, spacing of 
characters, and so forth. 

3. Process the file with the DCL command RUNOFF. 

When DSR processes the source file, the DSR commands cause the text to be 
formatted into sections, paragraphs, lists, and so on. Neither the DSR commands 
nor the DSR flags appear in the final document. 

10.1 Entering DSR Commands 

To enter a DSR command, create the source file with EDT, EVE, or another text 
editor. Begin the command in column 1 of a line and precede the command with 
a period. For example, to insert a blank line between two lines of text, enter the 
DSR command .BLANK, as follows: 

We sail the ocean blue, 

. BLANK 

And our saucy ship's a beauty. 

Most DSR commands have standard abbreviations. For example, you can 
abbreviate the .NO CONTROL CHARACTERS command as .NCC. For a list of 
DSR commands and their standard abbreviations, see Table 10-4. 

10.2 Invoking DSR to Process Your Files 

After you add DSR commands to your file and exit from the editor, you are 
ready to process the file with DSR. To invoke DSR, enter the RUNOFF command 
followed by the name of the file you want to process. For example, to process a 
file named FUN. RNO, enter the following command line: 

$ RUNOFF FUN 
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If you process a file with the file type .RNO, you need only to enter the file name, 
not the file type. To process a file named FUN.FUN, enter both the file name and 
the file type, as follows: 

$ RUNOFF FUN.FUN 

By default, the RUNOFF command produces an output file with the same name 
as the input file and the file type .MEM. The preceding examples produce an 
output file named FUN.MEM. 

10.2.1 Overriding DSR Commands or Flags 

By using qualifiers with the RUNOFF command, you can override DSR 
commands or flags included in your text file. For example, the /NOBOLD 
qualifier suppresses any bolding you may have specified in the file by using the 
DSR command .FLAGS BOLD: 

$ RUNOFF /N0B0LD FUN 

RUNOFF command qualifiers allow you to alter the position of the text on all 
pages of the document, to specify emphasis such as underlining and bolding, and 
to otherwise control the appearance of printed output. 

Table 10-1 summarizes the RUNOFF command qualifiers. 


Table 10-1 RUNOFF Command Qualifiers 


Qualifier 


Description 


/BACKSPACE 


/[NOJBOLD 

/[NO]CHANGE_BARS 

/CONTENTS 

/[NOJDEBUG 

/DEVICE 

/DOWN 

/INDEX 

/FORM_SIZE 

/[NOJINTERMEDI ATE 

/[NOJLOG 

/MESSAGES 

/[NOJOUTPUT 


Uses the Backspace character to bold, overstrike, or underline text as 
it is printed. This generally gives more exact underlining and bolding 
for files printed on letter-quality printers. The /BACKSPACE qualifier 
is not recommended for line printers. 

Enables and disables bolding. Any bolding specified in chapter and 
header titles appears in the table of contents. 

Enables and disables the appearance of change bars in the output file. 

Generates a table of contents. (See Section 10.3.) 

Traces the operation of certain DSR commands by causing the 
commands to appear in the output file. 

Specifies printing options. 

Specifies the number of blank lines to be inserted at the top of each 
page, preceding any header information. 

Generates an index. (See Section 10.4.) 

Controls the number of lines that can be accommodated per page of 
output. 

Generates an intermediate binary file with the default file type .BRN 
for use with the DSR Table of Contents utility and the DSR Indexing 
utility. 

Controls whether or not DSR displays processing information at your 
terminal. 

Lets you specify whether you want error messages displayed on your 
terminal or in an output file only. By default, DSR displays messages 
in both places. 

Specifies the name of the output file produced by DSR. 

(continued on next page) 
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Table 10-1 (Cont.) RUNOFF Command Qualifiers 
Qualifier Description 


/PAGES 
/[NO]PAUSE 
/REVERSE EMPHASIS 


/[NO]RI GHT 

/SEPARATEJJNDERLINE 

/[NO]SEQUENCE 
/[NO]SI MULATE 

/[NO]UNDERLINE_CHAR 

/VARIANT 


Limits the output file to a specified range of pages. 

Controls whether DSR pauses after printing each page of output. 

Specifies that underlining of flagged text is to be done after the text 
is printed. By default, the printer prints the underscores, issues a 
carriage return without a line feed, then prints the flagged text above 
the underscores. 

Causes the text on each page to be shifted to the right. 

Underlines text by using separate characters on the next line instead of 
overprinting with underscores on the same line. 

Controls whether DSR outputs line numbers from the input file. 

Controls whether blank lines or form feeds are used to advance to the 
top of each page. 

Allows you to specify the character to be used for underlining of flagged 
text. 

Controls the execution of the condition commands (.IF, .IF NOT, .ELSE, 
.ENDI F) by specifying the names of the segments to be processed. 


See the OpenVMS DIGITAL Standard Runoff Rrference M anual or refer to DCL 
Help for a complete description of the RUNOFF commands and qualifiers. 

10.2.2 Using DSR Defaults 

When you use DSR to process a file, your output file looks different from your 
input file because DSR provides the following standard format default settings: 

• A standard typewriter page size of 8 1/2 x 11 inches; that is, a width of 70 
character positions and a length of 58 lines of text per page (.PAGE SIZE 
58,70) 

• Sequential page numbering for every page but the first (.PAGI NG) 

• A left margin setting of 0 (just before the first character position of a line) and 
a right margin setting of 70 (just after the 70th character position of a line) 
(.LEFT MARGIN 0 and .RIGHT MARGIN 70) 

• Line spacing equivalent to the single-space setting on a typewriter 
(.SPACING 1) 

• A tab setting every eighth character position on a line (.TAB STOPS 8, 16, 

24, ...) 

• Filling: DSR fills each line with as many words as possible until the addition 
of another complete word would exceed the right margin (.FILL) 

• J ustification: DSR adds spaces between words to expand each line exactly to 
the right margin, making the right margin even or justified (.J USTIFY) 

If you do not want your file to be formatted according to the DSR default 
commands (shown in parentheses in the preceding list), you must disable them. 
See the OpenVMS DIGITAL Standard Runoff Reference M anual for a complete 
list of the default commands provided by DSR and the commands you need to 
disable them. 
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10.3 Creating a Table of Contents 

To create a table of contents, perform the following steps: 

1. Generate an intermediate (binary) file. For example: 

S RUNOFF /INTERMEDIATE FUN.RNO 

Be sure to specify an .RNO file type. DSR produces a file with a .BRN file 
type, which contains both table of contents and indexing information. 

2. Run the Table of Contents utility. 

S RUNOFF/CONTENTS FUN. BRN 

Be sure to specify a .BRN file type. You can add qualifiers to this command 
line to customize the table of contents. DSR produces a file with an .RNT file 
type. 

3. Process the .RNT file. 

S RUNOFF file. RNT 

Be sure to specify an .RNT file type. DSR produces a file with an .MEC file 
type, which contains the table of contents. 

The RUNOFF/CONTENTS command produces a table of contents with the 
following features: 

• Chapter titles and numbers (generated by the .CFIAPTER command). 

• Section titles and numbers (generated by the .HEADER LEVEL command). 
By default, DSR allows up to six levels of headers to appear in the table of 
contents. 

• Appendix titles and letters (generated by the .APPENDIX command). 

• Chapter-oriented page numbers (1-1, 1-2, 1-3, ... ) for all table of contents 
entries. 

• An output file with the same name as the input file. 

The following example shows a table of contents produced by DSR default values. 
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Table of Contents Example 

$ TYPE FUN.MEC 

CONTENTS 

CHAPTER 1 How to Tile a Floor 


1.1 Reading About Tiling 1-1 

1.1.1 Tiling for Fun 1-2 

1.1.2 Your Home in Tile 1-3 

1.1.3 Changing a Room with Tile 1-3 

1.2 Buying the Tile 1-5 

1.2.1 Researching Tiles Produced Abroad. . . 1-5 

1.2.2 Coordinating Colors 1-6 

1.2.3 Tile Textures 1-6 

1.2.4 Types of Tiles 1-7 

1.2. 4.1 Ceramic 1-7 

1.2. 4. 2 Clay 1-7 

1.3 Tools for Tiles 1-8 

1.3.1 Renting a Cutter 1-8 

1.3.2 Buying or Renting Crimpers 1-9 

1.4 Accompanying Materials 1-9 

1.4.1 How to Adhere the Tiles 1-9 

1.4.2 Grout 1-10 

CHAPTER 2 How to Cedar a Ceiling 

2.1 Getting Started 2-1 

2.1.1 Various Surfaces 2-2 


To tailor the DSR Table of Contents utility to meet your own needs, use the 
qualifiers listed in Table 10-2. 


Table 10-2 DSR Qualifiers for Tailoring a Table of Contents 

Qualifier Result 


/BOLD 

/DEEPEST_HEADER=n 

/IDENTIFICATION 

/INDENT 

/LOG 

/OUTPUT =newfile 
/NOOUTPUT 

/PAGE_NUMBERS=RUNNING 


Enables bolding of chapter and header titles in the 
table of contents. 

Displays header levels up to and including level n. 

Displays the current version number of the DSR 
Table of Contents utility. 

Indents each header level after header level 1, two 
spaces beyond the preceding header level. 

Reports the name of each input file as it is 
processed and after it is processed, plus the name 
of the generated output file. 

Specifies the name of the output file produced by 
DSR. The /NOOUTPUT qualifier causes DSR to 
process the input file without creating an output 
file. 

Uses running page numbers instead of chapter- 
oriented page numbers for all table of contents 
entries, whether or not you specified running page 
numbers in the document. 


(continued on next page) 
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Table 10-2 (Cont.) DSR Qualifiers for Tailoring a Table of Contents 


Qualifier 

Result 

/REQUIRE=filespec 

Allows you to change the heading on the first page 
of a table of contents. 

/NOSECTION_N UMBERS 

Suppresses the display of section numbers for all 
header levels. 

/UNDERLINE 

Includes underlining specified in chapter and 
header titles in the table of contents. 


The following example shows how to change the display of page numbers from 
chapter-oriented numbers (1-1, 1-2, 1-3, . . . ) to running numbers (1, 2, 3, . . . ). 

Changing Page Number Display in a Table of Contents Example 

$ RUNOFF / CONTENTS /PAGE_NUMBERS=RUNNING 

CONTENTS 


CHAPTER 1 How to Tile a Floor 


1.1 Reading About Tiling 1 

1.1.1 Tiling for Fun 2 

1.1.2 Your Home in Tile 3 

1.1.3 Changing a Room with Tile 3 

1.2 Buying the Tile 5 

1.2.1 Researching Tiles Produced Abroad. ... 5 

1.2.2 Coordinating Colors 6 

1.2.3 Tile Textures 6 

1.2.4 Types of Tiles 7 

1.2. 4.1 Ceramic 7 

1.2. 4. 2 Clay 7 

1.3 Tools for Tiles 8 

1.3.1 Renting a Cutter 8 

1.3.2 Buying or Renting Crimpers 9 

1.4 Accompanying Materials 9 

1.4.1 How to Adhere the Tiles 9 

1.4.2 Grout 10 

CHAPTER 2 How to Cedar a Ceiling 

2.1 Getting Started 1 

2.1.1 Various Surfaces 2 


10.4 Creating an Index 

To create an index, enter .INDEX and .ENTRY commands throughout your file. 
The .INDEX flag will create an index entry with an associated page number. 

The .ENTRY command will create an index entry without a page number, and is 
usually used for "See" and "See also" entries. The format for an index entry is as 
follows: 

.INDEX topic> subtopio subtopic 
.ENTRY topic [>subtopic >subtopic] 

For example, if you want the word "Chopin", with a subtopic of "Frederic" 
to appear in your index, enter the .INDEX command followed by the words 
"Chopin>Frederic": 

The music was soft and romantic, and Marvin knew at once that it 
.ENABLE INDEXING 
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. XLOWER 

.INDEX Chopin>Frederic 

was a waltz by Frederic Chopin that held his attention. 

I n the above example, the .ENABLE INDEXING flag enables the operation of the 
other index commands (.XLOWER and .INDEX). The .XLOWER flag determines 
that the case of all index entries will be exactly as entered (as opposed to the 
.XUPPER flag, which automatically capitalizes the first character of every entry 
and drops everything else in the entry lowercase). 

After you enter the index commands in your file, perform the following three 
steps: 

1. Generate an intermediate (binary) file. For example: 

$ RUNOFF/ INTERMEDIATE FUN.RNO 

Be sure to specify an .RNO file type. DSR produces a file with the file type 
.BRN. 

2. Run the I ndexing utility. 

$ RUNOFF/ INDEX FUN. BRN 

Be sure to specify a .BRN file type. You can add qualifiers to this command 
line to customize the I ndexing utility. DSR produces a file with the file type 
.RNX. 

3. Process the .RNX file. 

$ RUNOFF FUN. RNX 

Be sure to specify an .RNX file type. DSR produces a file with the file type 
.MEX, which contains an index. 

The RUNOFF/I NDEX command produces an index with the following features: 

• Fifty-five lines per page, including the top and bottom header areas 

• Chapter-oriented page numbers for index entries 

• Consecutive page numbers merged into ranges 

• An output file with the same name as the input file 
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The following example shows an index produced by DSR default values: 

Using DSR Default Values to Create an Index Example 

$ TYPE FUN.MEX 


Page Index-1 


INDEX 


Amadeus 

See Mozart, Wolfgang Amadeus 

Bach, Carl Phillip Emanuel, 1-2 
to 1-4, 4-9 

Bach, Johann Sebastian, 1-1, 3-2, 
4-9, 4-12 
Baroque composer 

See Bach, Johann Sebastian 
Bartok, Bela, 2-1, 3-4, 4-10, 

4-13 

Britten, Benjamin, 4-3, 4-14 

Ceremony of Carols 
See Britten, Benjamin 
Chopin, Frederic, 4-1 to 4-4 
4-14 

Debussy, Claude, 3-3, 4-13 

French composer 

See Debussy, Claude 

Hindemith, Paul, 4-5 to 4-7, 4-15 


Liszt, Franz, 3-2, 4-11 

Mozart, Wolfgang Amadeus, 3-5, 
4-14 

Prokofiev, Sergei, 4-5, 4-15 

Rachmaninoff, Sergei, 3-3 to 3-6, 
4-13 

Rite of Spring 

See Stravinsky, Igor 

Satie, Erik, 2-2, 4-10 
Stravinsky, Igor, 4-7, 4-15 
Syrinx, 4-8, 4-17 

Velvet Gentleman 
See Satie, Erik 

Waltz 

See Chopin, Frederick 


To tailor the DSR Indexing utility to meet your own needs, use the qualifiers 
listed in Table 10-3. 


Table 10-3 DSR Qualifiers for Tailoring an Index 

Qualifier Result 


/IDENTIFICATION 
/LINE S_P E R_PAG E =n 


/LOG 

/OUTPUT =newfile 
/NOOUTPUT 

/PAGE NUMBERS=RUNNING 


Displays the current version number of the 
DSR I ndexing utility. 

Determines the number of lines of index 
entries on each page. The number n does 
not include the number of lines required for 
running heads and feet. 

Reports the name of each input file as it is 
processed and after it is processed, plus the 
name of the generated output file. 

Specifies the name of the output file produced 
by DSR. The /NOOUTPUT qualifier causes 
DSR to process your input file without 
creating an output file. 

Uses running page numbers instead of 
chapter-oriented page numbers for all index 
entries, whether or not you specified running 
page numbers in the document. 

(continued on next page) 
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Table 10-3 (Cont.) 

DSR Qualifiers for Tailoring an Index 

Qualifier 

Result 

/REQUI RE^filespec 

Allows you to change the heading on the first 
page of an index. 

/RESERVE=n 

Allows you to reserve n number of lines on the 
top of the first page of the index. 


I n the following example, DSR displays index pages that are 15 lines long: 

Example of a Tailored Index 

$ RUNOFF / INDEX/ LINES_PER_P AGE=1 5 

Page Index-1 


INDEX 


Amadeus 

See Mozart, Wolfgang Amadeus 

Bach, Carl Phillip Emanuel, 1-2 
to 1-4, 4-9 

Bach, Johann Sebastian, 1-1, 3-2, 
4-9, 4-12 
Baroque composer 

See Bach, Johann Sebastian 
Bartok, Bela, 2-1, 3-4, 4-10, 

4-13 


Hindemith, Paul, 4-5 to 4-7, 4-15 

Liszt, Franz, 3-2, 4-11 

Mozart, Wolfgang Amadeus, 3-5, 
4-14 

Prokofiev, Sergei, 4-5, 4-15 

Rachmaninoff, Sergei, 3-3 to 3-5, 
4-13 


Britten, Benjamin, 4-3, 4-14 

Ceremony of Carols 
See Britten, Benjamin 
Chopin, Frederic, 4-1 to 4-4, 
4-14 

Debussy, Claude, 3-3, 4-13 

French composer 

See Debussy, Claude 


Page Index-2 

Rite of Spring 

See Stravinsky, Igor 
Satie, Erik, 2-2, 4-10 
Stravinsky, Igor, 4-7, 4-15 
Syrinx, 4-8, 4-17 

Velvet Gentleman 
See Satie, Erik 

Waltz 

See Chopin, Frederic 


10.5 Summary of DSR Commands 

Table 10-4 lists all DSR commands, grouped by function. For complete command 
descriptions, refer toth eOpenVMS DIGITAL Standard Runoff Reference Manual 
or to DCL Help. 
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Table 10-4 Summary of DSR Commands 

Command Description 

Page-Formatting Commands — Page Size and Running Heads 


.AUTOSUBTITLE .AST 

.NO AUTOSUBTITLE .NAST 

.DATE .D 

.NO DATE .ND 

.FIRST TITLE .FT 


.HEADERS ON .HD 

.NO HEADERS .NHD 


.HEADERS UPPER .HD UPPER 

.HEADERS LOWER .HD LOWER 

.HEADERS MIXED .HD MIXED 


.LAYOUT .LO 

.PAGE SIZE .PS 

.SUBTITLE .ST 

.NO SUBTITLE .NST 

.TITLE .T 


Enable and disable use of section (.H EADER 
LEVEL) titles for running-head subtitles. 

Control whether or not the current date 
appears in running heads. Requires use of 
the .SUBTITLE command. 

Allows running-head information to 
appear on the first page of a document 
with no chapters. (See also .H E ADE RS 
ON, .LAYOUT, .TITLE, .SUBTITLE, and 
.AUTOSUBTITLE.) 

Restore and cancel the capability of having 
one or two lines of information, called 
running heads, at the top of a page. Running 
heads indicate the content of the page and 
the page number. 

These commands specify the case of the word 
"page" that precedes the page number. The 
commands produce, respectively, PAGE, page, 
and Page. In an index, these commands also 
affect the word "index" that is part of the 
page number (for example, Page Index-3). 

The command normally takes effect on the 
next page. 

Rearranges running-head and running-foot 
information on pages. 

Sets the page "frame" by specifying the page 
length (the maximum number of lines of text 
on a page) and the page width for the running 
heads. 

Allow you to specify a subtitle for a running 
head (see .HEADERS ON). 

Allows you to specify a title for a running 
head (see .HEADERS ON). This title 
normally appears at the top of every page 
but the first, at the leftmost position on the 
line (character position 0), regardless of the 
.LEFT MARGIN setting. (See also .FI RST 
TITLE, .SUBTITLE, and .LAYOUT.) 

(continued on next page) 
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Command 

Description 

Page-Formatting Commands — Paging and Page-Number Control 

.DISPLAY NUMBER 

.DNM 

Allows you to specify the form that sequential 
numbering (or lettering) of pages will take. 

.NO NUMBER 
.NUMBER PAGE 

.NNM 

.NMPG 

Suspend and resume normal page numbering. 
The .NUMBER PAGE command keeps track 
of the numbering while the .NO NUMBER 
command is in effect; or, it allows you to 
specify the beginning of a new number 
sequence by specifying a number for the 
next page. (Seealso .NUMBER RUNNING, 
.DISPLAY NUMBER, .NO PAGING, and 
.HEADERS ON.) 

.NUMBER RUNNING 

.NMR 

Allows you to specify the beginning of a new 
sequence of running page numbers. This 
command affects page numbers only if you 
have entered a .LAYOUT command with an 
nl value of 3. (See .LAYOUT, .HEADERS 

ON, and .NO NUMBER.) 

.PAGING 
.NO PAGING 

.PS 

.NPA 

Enable and disable paging, which splits a 
document into numbered pages and reserves 
space for running heads. This command has 
no effect on help files (files with the file type 
.RNH). 

Page-Formatting Commands— Subpaging 

.DISPLAY SUBPAGE 

.DSP 

Allows you to specify the form that sequential 
lettering (or numbering) of subpage 
characters will take. 

.NUMBER SUBPAGE 

.NMSPSG 

Allows you to specify the beginning of a new 
sequence of subpage numbers, for example, 1- 
16A, 1-16B, 1-16C, and so on. This command 
affects only the letters that the .SUBPAGE 
command appends to the normally numeric 
page number. .NUMBER SUBPAGE takes 
effect on the next page. (See also .SU BPAGE 
and .DISPLAY SUBPAGE.) 

.SUBPAGE 
.END SUBPAGE 

.SPG 

.ES 

Begin and end a new page and a new 
format for page numbering. (See also 
.NUMBER SUBPAGE, .DISPLAY SUBPAGE, 
.HEADERS ON, .LAYOUT, and .PAGE.) 


(continued on next page) 
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Command 

Description 


Text-Formatting Commands- 

-Margin Setting 

.LEFT MARGIN 

.LM 

Sets the left margin to the specified position. 

.RIGHT MARGIN 

.RM 

Sets the right margin to the specified 
position. This is the position to which a 
line of text normally extends. If .J USTIFY is 
in effect, the .RIGHT MARGI N value is the 
position against which text i s j ustified. If .NO 
J USTIFY is in effect, the .RIGHT MARGIN 
value specifies the maximum number of 
characters on any text line. 

Text-Formatting Commands — Filling and Justifying 

.AUTOJ USTIFY 

•AJ 

The .AUTOJ USTIFY command automatically 

.NO AUTOJ USTIFY 

.NAJ 

justifies and fills text within the context of an 
appendix, chapter, section, or note. The .NO 
AUTOJ USTIFY command disables automatic 
justification. If you disable justification and 
filling with the .NO J USTI FY command, the 
settings for .[NOJFILL and .[NOJJ USTIFY 
will remain in effect. 

.FILL 

.F 

The .FILL command fills each line with 

.NO FILL 

.NF 

words until the addition of one more word 
would exceed the right margin. The .NO 

FILL command suspends both line filling and 
justification. 

.J USTIFY 

■J 

The .J USTIFY command inserts exactly 

.NO J USTIFY 

■NJ 

enough space between words so that the last 
character reaches the right margin. The .NO 

J USTIFY command disables justification. 


Text-Formatting Commands— 

-Vertical Spacing 

.BLANK 

.B 

1 nserts exactly the number of blank lines that 
you specify (for example, ,B2, ,B3). 

.BREAK 

.BR 

Ends the current line immediately, without 
filling or justifying the text. 

.KEEP 

.K 

Allow you to keep or not keep blank lines 

.NO KEEP 

.NK 

in the output that are present in the input 
file when .NO FI LL is in effect. Normally 
multiple blank lines in the input file are 
discarded. (See also .LITERAL.) 

.SKIP 

.S 

Inserts a multiple of the number of 
blank lines that has been specified by the 
.SPACING command. 

.SPACING 

.SP 

Changes the amount of spacing between lines 
of text. 


(continued on next page) 
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Text-Formatting Commands — Vertical Spacing 


.PAGE .PG Starts a new page. 

.TEST PAGE .TP Allows you to keep a specified amount of 

text entirely on a single page. If there is 
not enough room on the current page to 
accommodate that amount, DSR ends the 
current page and puts the entire text on the 
next page. 



Text-Formatting Commands- 

—Horizontal Spacing 

.CENTER 

.CENTRE 

.C 

Center a single line of text around a character 
position on a line. 

.INDENT 

.1 

Causes the first line of text following it to 
begin at a position relative to the left margin. 

.NO PERIOD 
.PERIOD 

.NPR 

.PR 

Cancel and restore the routine insertion of 
an extra space after any of the following 
punctuation marks: period (.), colon (:), 
question mark (?), and exclamation point (!). 

.RIGHT 

.R 

Positions a single line of text relative to the 
right margin. (See also .CENTER.) 

.TAB STOPS 

.TS 

Changes the current positions of tab stops. 
Each tab character in the input file advances 
the print carriage to the right to the next tab 
stop. 


Text-Formatting Commands— 

-Paragraph Formatting 


.AUTOPARAGRAPH 
.NO AUTOPARAGRAPH 

.AP 

.NAP 

Enable and disable starting a new paragraph 
each time a line starts with a space, a tab, or 
a blank line. Cancels .AUTOTABLE. 

.AUTOTABLE 
.NO AUTOTABLE 

.AT 

.NAT 

Enable and disable starting a new paragraph 
each time a line does not start with a space 
or a tab. Cancels .AUTOPARAGRAPH. 

.PARAGRAPH 

.P 

Controls spacing and page placement 
associated with the creation of paragraphs. 
(See also .SET PARAGRAPH.) 

.SET PARAGRAPH 

.SPR 

Allows you to set values for .PARAGRAPH 
without entering .PARAGRAPH (for example, 
when you are using .AUTOPARAGRAPH). 


(continued on next page) 
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Command 

Description 


Text-Formatting Commands- 

—Text Emphasis 

.ENABLE BAR 
.DISABLE BAR 

.EBB 

.DBB 

Enable and disable the use of change bars, 
vertical bars ( | ) inserted to indicate where 
changes in text have occurred since the 
previous edition of a document. 

.BEGIN BAR 
.END BAR 

.BB 

.EB 

Determine where DSR starts and stops 
inserting change bars at the beginning of 
lines. 

.ENABLE BOLDING 
.DISABLE BOLDING 

.EBO 

.DBO 

Enable and disable use of the Bold flag (* ) to 
indicate bolding, if the .FLAGS BOLD flag is 
enabled. 

.ENABLE HYPHENATION 
.DISABLE HYPHENATION 

.EHY 

.DHY 

Enable and disable use of the Hyphenate flag 
( =) to indicate hyphenation, if the .FLAGS 
HYPHENATE flag is enabled. 

.ENABLE OVERSTRIKING 
.DISABLE OVERSTRIKING 

.EOV 

.DOV 

Enable and disable use of the Overstrike flag 
(%) to create special characters that are not 
available on the terminal by overstriking any 
printing character with another. Recognition 
of the .FLAGS OVERSTRIKE flag must be 
enabled. 

.ENABLE UNDERLINING 
.DISABLE UNDERLINING 

.EUN 

.DUL 

Enable and disable use of the Underline 
flag (& ) to underline text, if the .FLAGS 

U NDE RLI NE flag is enabled. 

Text-Formatting Commands — Figures 

.FIGURE 

.FG 

Leaves room on a page for you to insert a 
figure later. If there is not enough room 
on the current page, DSR ends the page 
immediately and then puts the blank lines at 
the top of the next page. 

.FIGURE DEFERRED 

.FGD 

Leaves room on a page for you to insert a 
figure later. If there is not enough room on 
the current page, .FIGURE DEFERRED first 
adds enough text to complete the page and 
then puts the required number of blank lines 
at the top of the next page. 

.LITERAL 
.END LITERAL 

.LT 

.EL 

Allow you to have your text formatted exactly 
as you have typed it. DSR commands and 


flags are not recognized and are treated as 
ordinary text. Tab stops set prior to the 
.LITERAL command, however, remain in 
effect (see .TAB STOPS). 

(continued on next page) 
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Description 

Text-Formatting Commands — Lists 

.DISPLAY ELEMENTS 

.DLE 

Allows you to specify the form that sequential 
numbering or lettering of items in a list will 
take. 

.LIST 

.END LIST 

.LS 

.ELS 

The .LIST command specifies the beginning 
of a list by resetting the left margin farther to 
the right, by setting a .SKIP command value 
to take effect before each item in the list, and 
by executing the .TEST PAGE command. 



The .END LIST command ends a list, 
restoring any fill, justify, case, margin, or 
spacing settings that were in effect before you 
entered the most recent .LIST command. 

.LIST ELEMENT 

.LE 

Specifies the beginning of each item in a list. 

.NUMBER LIST 

.NMLS 

Allows you to specify, anywhere in a list, the 
number with which a sequence of items in 
a list will begin. Enter this command just 
before the .LIST ELEMENT command that 
you want to affect. Subsequent list elements 
will each have a number that is one greater 
than the number for the preceding .LIST 
ELEMENT command. (See also .DISPLAY 
ELEMENTS, with which you can specify the 
form the number will take.) 


Text-Formatting Commands— 

-Notes and Footnotes 

.FOOTNOTE 
.END FOOTNOTE 

.FN 

.EFN 

The .FOOTNOTE command places text at 
the bottom of the current page. If there is 
not enough space on the current page for the 
entire footnote, DSR places the entire note at 
the bottom of the next page. 



The .END FOOTNOTE command ends the 
footnote and restores any case, fill, justify, 
spacing, or margin settings that you might 
have changed within the footnote. 

.NOTE 
.END NOTE 

.NT 

.EN 

The .NOTE command highlights a portion 
of text by narrowing the margin settings, 


centering the text on the page, and printing a 
title centered over the text. 


The .END NOTE command restores the fill, 
justify, case, margin, and spacing settings 
that were in effect just before you entered the 
.NOTE. 


(continued on next page) 
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Section-Formatting Commands- 

-Appendixes and Chapters 

.APPENDIX 

.AX 

Specifies the beginning of an appendix, 
assigns an identifying letter to it, and allows 
you to supply a title. 

.CHAPTER 

.CH 

Specifies the beginning of a chapter, assigns 
an identifying number to it, and allows you to 
supply a title. 

.DISPLAY APPENDIX 

.DAX 

Allows you to specify the form that the 
lettering (or numbering) of appendixes 
will take. The form you specify appears 
in the title, the page numbers, and the first 
character of header-level numbers throughout 
the appendix. 

.DISPLAY CHAPTER 

.DCH 

Allows you to specify the form that the 
numbering (or lettering) of chapters will take. 
The form you specify appears in the title, 
the page numbers, and the first character of 
header-level numbers throughout the chapter. 

.NUMBER APPENDIX 

.NMAX 

Allows you to specify an identifying letter 
with which a sequence of appendixes will 
begin. The next .APPENDIX command 
starts the sequence. Subsequent .APPENDIX 
commands cause appendixes to be lettered 
in alphabetic order. (See also .Dl SPLAY 
APPENDIX.) 

.NUMBER CHAPTER 

.NMCH 

Allows you to specify the number with which 
a sequence of chapters will begin. The next 
.CHAPTER command starts the sequence. 
Subsequent .CHAPTER commands will cause 
each chapter to be numbered one higher than 
the previous chapter. (See also .DISPLAY 
CHAPTER.) 

Section-Formatting Commands — Sections 

.DISPLAY LEVELS 

.DHL 

Allows you to specify the form that sequential 
numbering (or lettering) of section headers 
will take. 

.HEADER LEVEL 

.HL 

Allows you to specify both a section number 
and a section title. Successive .HEADER 
LEVEL commands of the same value (all 
.HEADER LEVEL 1 commands, for example) 
cause the section numbers to increase 
sequentially. 

.NUMBER LEVEL 

.NMLV 

Allows you to specify the beginning number 
of a sequence of headers. (See also .STYLE 
HEADERS and .DISPLAY LEVELS.) 

.SET LEVEL 

.SL 

Allows you to preset the level of the next 
section head without entering a .HEADER 
LEVEL command (see .HEADER LEVEL). 


(continued on next page) 
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Section-Formatting Commands — Sections 

.STYLE HEADERS 

.STHL 

Changes the formats of the various levels of 
section headers (.HEADER LEVEL n). 

Section-Formatting Commands — Indexes 

.ENABLE INDEXING 

. E 1 X 

Enable and disable the operation of the 

.DISABLE INDEXING 

.DIX 

indexing commands (.INDEX and .ENTRY) 
and the 1 ndex flag ( >). 

.ENTRY 

.Y 

Creates an index entry without a page 
number reference. It is usually used for 
See... or Seealso... index entries. 

.FLAGS INDEX 

.FL INDEX 

Enable and disable recognition of the Index 

.NO FLAGS INDEX 

.NFL INDEX 

flag character ( >). 

.FLAGS SUBINDEX 

.FL SUBINDEX 

Enable and disable recognition of the 

.NO FLAGS SUBINDEX 

.NFL SUBINDEX 

Subindex flag (>). The .FLAGS SUBINDEX 
command can change the Subindex flag 
to another character. The .NO FLAGS 



SU Bl N DEX can include a right angle bracket 
( >) as part of your indexed text, instead of 
causing subindexing. 

.INDEX 

.X 

Creates an index entry with a page number 
reference. 

.XLOWER 

.XL 

Determine whether you control the case of 

.XUPPER 

.XU 

index entries specified by the .INDEX and the 
.E NTRY commands or by the 1 ndex flag ( >). 
When you enter the .XLOWER command, 
the case of the index entries matches exactly 
the case that you enter when you make the 
index entry. When you enter the .XUPPER 
command, DSR capitalizes the first character 
of every index entry and drops everything 
else in the entry to lowercase. 


Section-Formatting Commands- 

-Table of Contents 

.ENABLE TOC 

.ETC 

Enable and disable use of information 

.DISABLE TOC 

.DTC 

collected by DSR to create a table of contents. 

.SEND TOC 

.STC 

Allows you to control the appearance of the 
table of contents (.RNT) file by inserting DSR 
commands, DSR flags, and text. 


(continued on next page) 
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Flag-Recognition Commands 


.FLAGS ACCEPT 
.NO FLAGS ACCEPT 


.FL ACCEPT 
.NFL ACCEPT 


.FLAGS ALL .FL 

.NO FLAGS ALL .NFL 


.FLAGS BOLD .FL BOLD 

.NO FLAGS BOLD .NFL BOLD 


.FLAGS BREAK 
.NO FLAGS BREAK 


.FL BREAK 
.NFL BREAK 


.FLAGS CAPITALIZE .FL CAPITALIZE 

.NO FLAGS CAPITALIZE .NFL CAPITALIZE 


Control recognition of the Accept flag 
character (_). 

Serve as master switches for all other flag 
(.FLAG and .NO FLAG) settings, except 
the .FLAGS COMMENT, .NO FLAGS 
COMMENT, .FLAGS CONTROL, and .NO 
FLAGS CONTROL commands. 

The .FLAGS ALL and .NO FLAGS ALL 
commands enable and disable recognition 
of all flags without disturbing other flag 
command settings. (An analogy for flag 
recognition is turning on a master switch 
[entering .FLAGS ALL] — those lights with 
switches in the ON position will go on and 
those with switches in the OFF position will 
not go on.) See also .ENABLE BOLDING and 
.DISABLE BOLDING, .HYPHENATION, 
.INDEXING, .OVERSTRIKING, and 
.UNDERLINING commands. 

Enable and disable recognition of the Bold 
flag character (*). 

Enable and disable recognition of the Break 
flag character ( | ), which specifies the place 
at which a new page should begin. 

Enable and disable recognition of the 
Capitalize flag character (<). 


.FLAGS COMMENT 
.NO FLAGS COMMENT 


.FL COMMENT 
.NFL COMMENT 


.FLAGS CONTROL 
.NO FLAGS CONTROL 


.FL CONTROL 
.NFL CONTROL 


.FLAGS HYPHENATE .FL HYPHENATE 

.NO FLAGS HYPHENATE .NFL HYPHENATE 


Enable and disable recognition of the 
Comment flag character ( ! ). 

Control recognition of the Control flag 
character (the period that begins a DSR 
command). The .FLAGS CONTROL 
command changes the character that precedes 
the commands from a period to a character 
of your choice. The .NO FLAGS CONTROL 
command disables recognition of the Control 
flag character. 

Enable and disable recognition of the 
Hyphenate flag character ( =). 


.FLAGS LOWERCASE .FL LOWERCASE Enable and disable recognition of the 

.NO FLAGS LOWERCASE .NFL LOWERCASE Lowercase flag character (\ ). 


.FLAGS OVERSTRIKE .FL OVERSTRI KE Enable and disable recognition of the 

.NO FLAGS OVERSTRIKE .NFL OVERSTRIKE Overstrike flag character ( %). 


.FLAGS PERIOD .FL PERIOD 

.NO FLAGS PERIOD .NFL PERIOD 


Enable and disable recognition of the Period 
flag character ( +). 


.FLAGS SPACE .FL SPACE 

.NO FLAGS SPACE .NFL SPACE 


Enable and disable recognition of the Space 
flag character (#). 


(continued on next page) 
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Description 

Flag-Recognition Commands 

.FLAGS SUBSTITUTE 
.NO FLAGS SUBSTITUTE 

.FL SUBSTITUTE 
.NFL SUBSTITUTE 

Enable and disable recognition of the 
Substitute flag character ( $). Note that you 
must use a pair of Substitute flag characters 
to make the substitution occur. 

.FLAGS UNDERLINE 
.NO FLAGS UNDERLINE 

.FL UNDERLINE 
.NFL UNDERLINE 

Enable and disable recognition of the 
Underline flag character (& ). 

.FLAGS UPPERCASE 
.NO FLAGS UPPERCASE 

.FL UPPERCASE 
.NFL UPPERCASE 

Enable and disable recognition of the 
Uppercase flag ( ~). 

Miscellaneous Commands 

.CONTROL CHARACTERS 
.NO CONTROL 
CHARACTERS 

.CC 

.NCC 

Enable and disable use of control characters 
as normal text in your input file. 

.IF 

.1 FNOT 

.ELSE 

.ENDIF 

.El 

.IN 

Cause portions of a DSR file to be processed 
or not processed, according to conditions that 
you specify. 

.NO SPACE 

.NSP 

Prevents the insertion of the end-of-line 
space for one line of text only, causing the 
characters at the end of one line and the 
beginning of the next to be adjacent. 

.REPEAT 

.RPT 

Allows you to specify up to 150 characters to 
be printed a specified number of times, either 
horizontally or vertically. 

.REQUIRE 

.REQ 

Allows you to process several DSR files at the 
same time and merge them in an output file. 

.SAVE 

.RESTORE 

.SA 

.RE 

Maintain the current RUNOFF formatting 
context of a document, including DSR 
defaults as well as DSR commands and 
flags. 

.SET DATE 
.SET TIME 

.SDT 

.STM 

Specify a date and time to be inserted in your 
file when you use the Substitute flag pair, 

$$, with any of the appropriate date or time 
parameters. The .SET DATE command also 
sets the date for the .DATE command, which 
causes the date to appear in running heads. 

.VARIABLE 

.VR 

Allows you to specify a character that 
corresponds to the name you have given 
the commands and text in an .IF (or 
.IFNOT) block. This identifying character 
is placed in the left margin when you 
process your file with the /DEBUG or 
/DE BUG=CONDITI ONALS command line 
qualifier. 
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Sort/Merge Utility: Sorting and Merging Files 


This chapter describes how to use the OpenVMS Sort/Merge utility 
(SORT/MERGE) to perform the following tasks: 

• Sort records from one or more input files according to the fields you select, 
and generate one reordered output file. 

• Merge up to 10 input files that have been sorted previously according to the 
same key fields, and generate one output file. 

• E nter records to be sorted or merged from a termi nal . 

• Use a Sort/Merge specification file. 

• Optimize a sort or merge operation. 


11.1 Sorting Files 

To sort files, use the DCL command SORT. Specify both the name of the file to be 
sorted and the name of the ordered output file to be created. For example, to sort 
the file NAMES. LST in ascending order, enter the following command: 

S SORT NAMES. LST BYNAME. LST 

This command creates the ordered output file BYNAME. LST, as shown in 
Figure 11-1. 


Figure 11-1 List Sorted in Ascending Order 


NAMES. LST 

MCMAHON JANE 
IMPOSTER HARRY 
ROSENBERG HARRY 
KNIGHT MARTHA 
BENTLEY PETER 
BENTLEY PETER 
LOWELL FRANK 


♦ 


BYNAME. LST 

BENTLEY PETER 
BENTLEY PETER 
IMPOSTER HARRY 
KNIGHT MARTHA 
LOWELL FRANK 
MCMAHON JANE 
ROSENBERG HARRY 


ZK-5055A-GE 


You can also specify multiple input files. For example, the following command 
sorts the files NAMES. LST and NAMES2.LST into the ordered output file 
BYNAME. LST. 

$ SORT NAMES. LST, NAMES2. LST BYNAME. LST 

Sort treats the files as if they were one large file. 
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11.1.1 Sorting File Records 

Record sorting is the default sort operation. It keeps records intact and 
produces an output file consisting of complete records. Sort also lets you sort 
individual segments, or fields, of a record. To subdivide a record into fields, 
specify the starting position and the length of the field. A record starting in the 
first byte of the record is position 1 (that is, it is the first character or space of the 
record). 

For example, each record in the file EM PLOYEE.LST consists of three fields: 
a department name, an account number, and a customer name. Figure 11-2 
illustrates these fields: 


Figure 11-2 Record Fields in a List 


EMPLOYEE.LST 

O 0 0 

BST 7828 MCMAHON JANE 
ADM 7933 IMPOSTER HARRY 
ADM 7933 ROSENBERG HARRY 
COM 8102 KNIGHT MARTHA 
ANS 8042 BENTLEY PETER 
ANS 5243 BENTLEY PETER 
BIO 7951 LOWELL FRANK 
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Sort arranges records from EMPLOYEE.LST according to the keys you specify, as 
follows: 

1 The department name begins in position 1 (the first byte of the record), is 
3 letters long, and contains character data. To sort by department name, 
describe the field with the /KEY qualifier, as follows: 

$ S0RT/KEY=(P0SITI0N:1,SIZE:3, CHARACTER) EMPLOYEE.LST BYDEPT.LST 

2 The account number begins in position 5 of the record, is 4 digits long, 
and contains decimal data. To sort by account number, enter the following 
command: 

S S0RT/KEY= (POSITION : 5, SIZE : 4 , DECIMAL) EMPLOYEE.LST BYACCOUNT . LST 

3 The customer name begins in position 10, is 15 letters long, and contains 
character data. To sort by customer name, enter the following command: 

$ S0RT/KEY= (POSITION: 10, SIZE: 15, CHARACTER) EMPLOYEE.LST BYNAME. LST 

The following sections describe how to sort records based on the contents of 
certain fields. You can arrange the records in ascending or descending order, 
alphabetically or numerically, depending on how you describe the key. For more 
detailed information on using keys and key fields, refer to online help. 
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Sorting Entire Records in Ascending Order 

By default, the SORT command uses a key field in a record that has the following 
characteristics: 

• Begins in the first position of a record 

• I ncl udes the enti re record 

• Contains character data 

• Sorts in ascending order 

For example, you can sort the file EMPLOYEE. LST without specifying a key field, 
as follows: 

$ SORT EMPLOYEE. LST BYDEPT.LST 

Because no key is specified, Sort assumes the default characteristics. The result 
of the sort are as shown in Figure 11-3: 


Figure 11-3 List Sorted Without Key Field 



EMPLOYEE. LST 



BYDEPT.LST 

BST 

7828 

MCMAHON JANE 


ADM 

7933 

IMPOSTER HARRY 

ADM 

7933 

IMPOSTER HARRY 


ADM 

7933 

ROSENBERG HARRY 

ADM 

7933 

ROSENBERG HARRY 


ANS 

5243 

BENTLEY PETER 

COM 

8102 

KNIGHT MARTHA 

» 

ANS 

8042 

BENTLEY PETER 

ANS 

8042 

BENTLEY PETER 


BIO 

7951 

LOWELL FRANK 

ANS 

5243 

BENTLEY PETER 


BST 

7828 

MCMAHON JANE 

BIO 

7951 

LOWELL FRANK 


COM 

8102 

KNIGHT MARTHA 


ZK-5057A-GE 

Sort uses each record in EMPLOYEE. LST as one key of character data. In this 
example, each record includes a department name, an account number, and a 
customer name. If Sort finds a duplicate department name, it sorts the names by 
account number. If it then finds a duplicate account number, it sorts by customer 
name. Note that the account number is part of the record. Unless you specify 
otherwise, it is treated as character data. 

Sorting Records by Key Field 

You can use the SORT command qualifier /KEY to specify the field in a record for 
sorting. You can also specify the order of the sort (ascending or descending). 

For example, to sort EMPLOYEE. LST by account number, use the /KEY qualifier 
to describe the account number field, as follows: 

$ S0RT/KEY= (POSITION : 5, SIZE : 4, DECIMAL) EMPLOYEE. LST BILLING1 .LST 

This command specifies that the key field (the account number) starts in position 
5, is 4 characters long, contains decimal data, and should be sorted in ascending 
order (the default). The results of the sort are as shown in Figure 11-4. 
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Figure 11-4 List Sorted by Key Field 



EMPLOYEE. LST 



BILLING1 .LST 

BST 

7828 

MCMAHON JANE 


ANS 

5243 

BENTLEY PETER 

ADM 

7933 

IMPOSTER HARRY 


BST 

7828 

MCMAHON JANE 

ADM 

7933 

ROSENBERG HARRY 


ADM 

7933 

ROSENBERG HARRY 

COM 

8102 

KNIGHT MARTHA 

» 

ADM 

7933 

IMPOSTER HARRY 

ANS 

8042 

BENTLEY PETER 


BIO 

7951 

LOWELL FRANK 

ANS 

5243 

BENTLEY PETER 


ANS 

8042 

BENTLEY PETER 

BIO 

7951 

LOWELL FRANK 


COM 

8102 

KNIGHT MARTHA 
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I n some cases, you might specify a key that extends beyond the end of a record. 
For example, the customer name field in EMPLOYEE. LST is 15 characters long, 
but not all names contain that many letters. To meet the size you specify, Sort 
treats the missing characters as null characters. 

11.1.1.1 Using Multiple Key Fields 

You can sort with more than one key (up to a limit of 255 keys). Specify multiple 
keys in order of their priority — specify the primary key first, the secondary key 
next, and so on. For example, the following command sorts EMPLOYEE. LST by 
the customer name key first and, then (where there are identical names), by the 
account number: 

$ SORT /KEY=(POSITION:10,SIZE:15, CHARACTER) - 

_$ /KEY= (POSITION: 5, SIZE: 4, DECIMAL) EMPLOYEE. LST BILLING2 .LST 

The results of the sort are as shown in Figure 11-5. 


Figure 11-5 List Sorted by Multiple Key Fields 



EMPLOYEE. LST 



BILLING2.LST 

BST 

7828 

MCMAHON JANE 


ANS 

5243 

BENTLEY PETER 

ADM 

7933 

IMPOSTER HARRY 


ANS 

8042 

BENTLEY PETER 

ADM 

7933 

ROSENBERG HARRY 


ADM 

7933 

IMPOSTER HARRY 

COM 

8102 

KNIGHT MARTHA 

» 

COM 

8102 

KNIGHT MARTHA 

ANS 

8042 

BENTLEY PETER 


BIO 

7951 

LOWELL FRANK 

ANS 

5243 

BENTLEY PETER 


BST 

7828 

MCMAHON JANE 

BIO 

7951 

LOWELL FRANK 


ADM 

7933 

ROSENBERG HARRY 
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Each key can be ascending or descending. For example, the following command 
sorts records first by the department name in descending order, then by the 
customer name in ascending order: 

$ S0RT/KEY=(P0SITI0N:1,SIZE:3, DESCENDING) - 
_$ /KEY= ( POSITION :10, SI ZE:15) - 
_$ EMPLOYEE. LST BILLING3 . LST 
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The results of the sort are as shown in Figure 11-6. 


Figure 11-6 List Sorted by Ascending and Descending Keys 



EMPLOYEE.LST 



BILLING3.LST 

BST 

7828 

MCMAHON JANE 


COM 

8102 

KNIGHT MARTHA 

ADM 

7933 

IMPOSTER HARRY 


BST 

7828 

MCMAHON JANE 

ADM 

7933 

ROSENBERG HARRY 


BIO 

7951 

LOWELL FRANK 

COM 

8102 

KNIGHT MARTHA 

» 

ANS 

5243 

BENTLEY PETER 

ANS 

8042 

BENTLEY PETER 


ANS 

8042 

BENTLEY PETER 

ANS 

5243 

BENTLEY PETER 


ADM 

7933 

IMPOSTER HARRY 

BIO 

7951 

LOWELL FRANK 


ADM 

7933 

ROSENBERG HARRY 
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11.1.1.2 Sorting Records with Identical Key Fields 

By default, Sort/Merge keeps records with identical key fields but does not 
necessarily maintain the same order in which they appeared in the input file. To 
control the way in which records with identical keys are sorted, specify one of the 
following qualifiers: 

• /STABLE 

Maintains the input order of records with identical keys. 

• /NODUPLICATES 

Retains only one copy of records with identical keys. 

For example, to eliminate records with duplicate account numbers from the file 
EMPLOYEE. LST, sort the file with the following command: 

$ SORT /KEY= (POSITION : 5, SIZE : 4) /NODUPLICATES EMPLOYEE. LST BUDGET. LST 

The results of the sort are as shown in Figure 11-7. 


Figure 11-7 List Sorted with Identical Keys 


EMPLOYEE.LST 

BST 7828 MCMAHON JANE 
ADM 7933 IMPOSTER HARRY 
ADM 7933 ROSENBERG HARRY 
COM 8102 KNIGHT MARTHA 
ANS 8042 BENTLEY PETER 
ANS 5243 BENTLEY PETER 
BIO 7951 LOWELL FRANK 


ANS 
BST 7828 
ADM 7933 
BIO 7951 
ANS 8042 
COM 8102 


— BUDGET.LST 

5243 BENTLEY PETER 


MCMAHON JANE 
IMPOSTER HARRY 
LOWELL FRANK 
BENTLEY PETER 
KNIGHT MARTHA 
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The /STABLE and /NODUPLICATES are incompatible. You cannot specify both 
qualifiers on the same command line. For more details, see the description of the 
/STABLE and /NODUPLICATES qualifiers in DCL Help. 
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11.1.2 Specifying a Different Output File Organization 

By default, Sort produces an output file with the same file organization as that 
of the first input file. To specify a different file organization, include one of the 
following qualifiers after the output file specification on the Sort command line: 

• /FORMAT (record format) 

When used as an output qualifier, you can define the file record format, 
length, and blocksize. 

• /I NDEXED_SEQUENTI AL- 
II sing this qualifier, you can define the output to have indexed sequential 
file organization. 

• /RELATIVE 

Using this qualifier, you can define the output to have relative file 
organization. 

• /SEQUENTIAL 

Using this qualifier, you can define the output to have sequential file 
organization. 

For example, to produce a sequential file after sorting the indexed sequential file 
EMPLOYEE.LST, enter the following command: 

$ S0RT/KEY= ( POSITION :10, SI ZE:15) - 
_$ EMPLOYEE.LST BYNAME . LST/SEQUENTIAL 

If you specify indexed sequential (/I NDEXED_SEQUENTI AL) as the output file 
organization, you must also do the following: 

• Before you perform the sort operation, create an empty file to be used as the 
output file. Sort requires an output file that already exists and is empty. 

• I nclude the /OVERLAY qualifier after the name of the output file on the 
SORT command line. The /OVERLAY qualifier indicates the existing file is to 
be overlaid with the sorted records of the input file. 

11.1.3 Specifying a Collating Sequence 

By default, the SORT command uses files that contain character data. Characters 
are sorted according to a collating sequence, which describes the order in which 
characters are arranged. 

ASCI I is the default collating sequence for character data. The ASCI I sequence 
orders numbers (0 to 9) first, then uppercase letters (A to Z), and then lowercase 
letters (a to z). 

You can specify the EBCDI C collating sequence to generate an output file that is 
ordered in EBCDIC sequence, although it remains in ASCII representation. The 
EBCDIC sequence orders lowercase letters (a to z) first, then uppercase letters (A 
to Z), and then numbers (0 to 9). To use the EBCDIC collating sequence, specify 
the /COLLATI NG_SEQUENCE=EBCDIC qualifier. 

The multinational collating sequence collates characters according to the DEC 
Multinational character set (see Appendix B). The multinational collating 
sequence compares characters in the following order: 

1. Different characters 

2. Different diacritical forms of the same character (formed by using diacritical 
[accent] marks as part of "compose sequences" on VT200 series terminals) 
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3. Different cases (uppercase or lowercase) of the same character 

To use the multinational collating sequence, specify the /COLLATING_ 
SEQUENCE=MULTI NATIONAL qualifier. 

To use a National character set (NCS) collating sequence, specify the name of 
the sequence after the /COLLATI NG_SEQUENCE qualifier (/COLLATI NG_ 
SEQUENCE=cs-name). Note that the collating sequence you specify must be 
defined in an NCS library. For more information, see th eOpenVMS National 
Character Set Utility Manual. 

You can also define your own collating sequence or modify these collating 
sequences through the use of a specification file. NCS collating sequences are 
an exception. They are supported only through the command line interface and 
not through specification files. Seethe/COLLATING_SEQUENCE description in 
DCL Help for more information. 


Note 

Exercise caution when using the multinational collating sequence to 
sort or merge files for further processing. Sequence-checking procedures 
in most programming languages compare numeric characters. Normal 
sequence checking does not work because the multinational sequence 
is based on actual graphic characters, not the codes representing those 
characters. 


11.1.4 Sorting Noncharacter Data Files 

If you sort files containing items other than character data, specify the data type 
of each key. In addition, take care in calculating starting positions and sizes 
because the items being compared can occupy more than 1 byte. For example, 
if you are sorting a file that contains 20 characters followed by 3 floating-point 
numbers in F_floating format, the positions are as follows: 

• The character data occupies positions 1 to 20 (20 characters). 

• The first F_floating-point number occupies positions 21 to 24. 

• The second F_floating-point number occupies positions 25 to 28. 

• The third F _fl oat ing- point number occupies positions 29 to 32. 

To sort the file by the third floating-point number, specify the key field as follows: 
$ S0RT/KEY= (POSITION : 29, F_FL0ATING) STATS. RAW STATS. SOR 

You do not need to specify the size of the floating-point number because it is fixed 
at four bytes. 

11.1.5 Running Sort as a Batch Job 

If you are sorting large files, consider submitting the sort operation as a batch 
job because the sort will require some time. Batch jobs are programs or DCL 
command procedures that run independently of your current session. See 
Chapter 17 and Chapter 15 for more information about batch jobs and command 
procedures, respectively. 
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If the records to be sorted are in a file, the command procedure you submit as 
a batch job must contain the SORT command. If your default directory does 
not contain the files to be sorted, explicitly set your default directory or include 
the directory in the command file specifications. The following example submits 
the DCL command procedure SORTJ OB.COM as a batch job. The text of the 
command procedure is shown following the command line: 

$ SUBMIT SORTJOB 
! SORTJOB.COM 

i 

$ SET DEFAULT [USER. PER] ! Set default to location of input files 
$ S0RT/KEY= (POSITION: 10, SIZE: 15) EMPLOYEE. LST BYNAME. LST 
$ TYPE BYNAME. LST 
$ EXIT 

You can include the input records in the batch job by placing them after the 
SORT command with one record per line (although individual sort records can 
be longer than one line). As with terminal input of records, you specify the input 
file parameter as SYS$I NPUT and qualify it with the record size in bytes and the 
approximate file size in blocks. (Approximately six 80-character lines equal one 
block.) 

The following is an example of including the input records in a command 
procedure: 

$ SUBMIT SORTJOB 
! SORTJOB.COM 

i 

$ SET DEFAULT [USER. PER] 

$ S0RT/KEY= (POSITION: 10, SIZE : 15) - 
SYS$INPUT- 

/FORMAT = ( REC0RD_S I ZE : 2 4 , F I LE_S I ZE : 1 0 ) - 
BYNAME. LST 
$ DECK 

BST 7828 MCMAHON JANE 
ADM 7933 ROSENBERG HARRY 
COM 8102 KNIGHT MARTHA 
ANS 8042 BENTLEY PETER 
BIO 7951 LOWELL FRANK 
$ E0D 


11.2 Merging Files 

The MERGE command combines up to 10 sorted files into one ordered output file. 
You can merge input files that have the same format and have been sorted by the 
same key fields. 

For example, if you sort the files BYNAME1.LST and BYNAME2.LST by 
customer name in ascending order, you can merge the files with the following 
command line: 

$ MERGE BYNAME1 . LST, BYNAME2 . LST BYNAME 3 .LST 

The output file BYNAME3.LST contains all the records from both files, 
BYNAME1.LST and BYNAME2.LST as shown in Figure 11-8. 
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Figure 11-8 Merged Lists 


BYNAME1 .LST 

BENTLEY PETER 
BENTLEY PETER 
IMPOSTER HARRY 
KNIGHT MARTHA 
LOWELL FRANK 
MCMAHON JANE 
ROSENBERG HARRY 


-BYNAME2.LST- 

COLE STUART 
DUPUIS KIM 
FLEMING MARIE 
MAHONEY RICK 


BYNAME3.LST 

BENTLEY PETER 
BENTLEY PETER 
COLE STUART 
DUPUIS KIM 
FLEMING MARIE 
IMPOSTER HARRY 
KNIGHT MARTHA 
LOWELL FRANK 
MAHONEY RICK 
MCMAHON JANE 
ROSENBERG HARRY 
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Merge checks the sequence of the records in the input files to be sure they are in 
order. If a record is out of order (for example, if you have not sorted one of the 
input files), Merge reports the following error: 

%S0RT-W-BAD_0RDER, merge input is out of order 

If you want to merge files that have not previously been sorted, you can prevent 
sequence checki ng by specifyi ng the /N OCH E CK_SEQU E N CE qual ifier. 

11.2.1 Merging Files Sorted by Key Field 

If you are merging files that have been sorted by a specific key field, describe the 
field with the /KEY qualifier on the MERGE command line. For example, assume 
the files Bl LLI NG1. LST and BILLING4.LST were sorted by account number 
(/KEY=POSITI ON :5, SI ZE:4, DECIMAL). To merge the files into the output file 
MAI LING. LST, enter the following command line: 

$ MERGE/KEY=(P0SITI0N=5, SIZE: 4, DECIMAL) - 
_$ BILLING1 . LST, BILLING4 .LST MAILING. LST 

The results of the merge are as shown in Figure 11-9. 
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Figure 11-9 Merged File Sorted by Key Field 


BILLING1 .LST 

ANS 5243 BENTLEY PETER 
BST 7828 MCMAHON JANE 
ADM 7933 ROSENBERG HARRY 
ADM 7933 IMPOSTER HARRY 
BIO 7951 LOWELL FRANK 
ANS 8042 BENTLEY PETER 
COM 8102 KNIGHT MARTHA 


BILLING4.LST 

COM 1192 DUPUIS KIM 
ADM 2398 COLE STUART 
BST 6342 MAHONEY RICK 
ADM 7483 FLEMING MARIE 


MAILING. LST 

COM 1192 DUPUIS KIM 
ADM 2398 COLE STUART 
ANS 5243 BENTLEY PETER 
BST 6342 MAHONEY RICK 
ADM 7483 FLEMING MARIE 
BST 7828 MCMAHON JANE 
ADM 7933 ROSENBERG HARRY 
ADM 7933 IMPOSTER HARRY 
BIO 7951 LOWELL FRANK 
ANS 8042 BENTLEY PETER 
COM 8102 KNIGHT MARTHA 
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You can use the same qualifiers with the MERGE command as you use with the 
SORT command with two exceptions: 

• You cannot specify a process (/PROCESS) for a merge operation. 

• The/CHECK_SEQUENCE qualifier is used only for a merge operation. 

11.2.2 Merging Records with Identical Key Fields 

As with a sort operation, when input files contain records with identical key 
fields, Merge does not necessarily maintain the same order in which the records 
had appeared in the input file. To maintain the input order of records with 
identical keys, specify /STABLE on the MERGE command line. To retain only one 
copy of records with identical keys, specify the /NODUPLI CATES qualifier. 

11.3 Entering Records from a Terminal 

The records to be sorted or merged do not have to be in a file. You can enter the 
records directly from the terminal as you enter the SORT or MERGE command. 
The steps are as follows: 

1. On the SORT or MERGE command line, specify SYS$I NPUT as the input 
file. Use the input file qualifier /FORMAT to specify the size of the longest 
record (in bytes) and the approximate size of the input file (in blocks). 

2. After you enter the SORT or MERGE command, enter the input records on 
successive terminal lines. 

3. End each record by pressing Return. 

4. End the file by pressing Ctrl/Z. 

The following example demonstrates a sort operation in which the input records 
to be sorted are entered directly from the terminal: 

$ S0RT/KEY= (POSITION: 8, SIZE: 15) - 

_$ SYS $ INPUT/FORMAT = (REC0RD_SIZE : 24, FILE_SIZE : 10) BYNAME. LST 
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BST 7828 MCMAHON JANE [Return] 

ADM 7933 ROSENBERG HARRY [Return] 

COM 8102 KNIGHT MARTHA [Return] 

ANS 8042 BENTLEY PETER |~Retum] 

BIO 7951 LOWELL FRANK [Return] 

| Ctrl/Z | 

This sequence of commands creates the output file BYNAME.LST, which contains 
the sorted records. 

11.4 Using a Sort/Merge Specification File 

Sort/Merge allows you to maintain sort definitions and to specify more complex 
sort criteria in specification files. These files may be created by any standard 
editor, or the DCL CREATE command. The Sort/Merge utility commands within 
a specification file are formatted differently than those on the DCL command line, 
and some have different meanings. Refer to Table 11-1 for more information on 
Sort/Merge utility command qualifiers. 

Each command in the specification file should start with a slash (/) and 
continuation characters are not required if a command spans more than one 
line. 

A Sort/Merge specification file allows you to do the following: 

• Select records to be included in the Sort/Merge operation 

• Reformat the records in the output file 

• Use conditional keys or data 

• Specify multiple record formats 

• Create or modify a collating sequence 

• Reassign work files 

• Store frequently used Sort/Merge operations 

You can use a text editor to create a specification file. Many of the qualifiers used 
in the specification file are similar to the DCL qualifiers used in the Sort/Merge 
command line. Note, however, that the syntax of these qualifiers can be different. 
For example, the /KEY qualifier at DCL level has different syntax than the /KEY 
qualifier in the specification file. 

Any DCL command qualifiers that you specify on the command line override 
corresponding entries in the specification file. For example, if you specify the 
/KEY qualifier in the DCL command line, Sort/Merge ignores the /KEY clause in 
the specification file. 

Generally, there is no required order in which you must specify the qualifiers in 
a specification file. The order does become significant, however, in the following 
cases: 

• Sorting by more than one key field 

• Descri bi ng the output format 

• Defining multiple record types 

When you specify the FOLD, MODIFICATION, and IGNORE keywords with the 
/COLLATI NG_SEQUENCE qualifier, you should specify all MODIFICATION and 
IGNORE clauses before any FOLD clauses. 
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You can include comments in your specification file by beginning each comment 
line with an exclamation point (!). Unlike DCL command lines, specification files 
do not need hyphens (-) to continue the line. 

After you create the text of the specification file, include the file name with the 
/SPECIFICATION qualifier. The default file type for a specification file is .SRT. 

11.4.1 Sample Specification File 

The following is an example of a specification file that can be used to sort negative 
and positive data in ascending order: 

! Specification file for sorting negative and positive data in ascending order 


i 

/FIELD= (NAME=SIGN, POS : 1 , SIZ : 1 ) 1 

/FIELD= (NAME=AMT, POS : 2, SIZ : 4 ) 2 

/CONDITION (NAME=CHECK1, 3 

TEST= (SIGN EQ ) 
/CONDITION (NAME=CHECK2, 4 

TEST= (SIGN EQ " ") ) 
/INCLUDE=(C0NDITI0N=CHECK1, 5 

KEY= (AMT, DESCENDING) , 
DATA=SIGN, 

DATA=AMT) 

/INCLUDE= (C0NDITI0N=CHECK2, 6 

KEY= (AMT, ASCENDING) , 
DATA=SIGN, 

DATA=AMT) 


This sample specification file accomplishes the following tasks: 

1 This command line assigns the name SIGN to the first byte of a record and 
assigns a position of 1 and a size of 1. 

2 This command line assigns the name AMT to the second byte of a record and 
assigns a position of 2 and a size of 4. 

3 This is a condition statement. If there is a negativesign (-) in the SIGN byte, 
the condition CHECK1 is met. 

4 This is a condition statement. If the SIGN byte is blank, the condition 
CHECK2 is met. 

5 If the condition CHECK1 is met, then the record will be sorted in descending 
order. 

6 If the condition CHECK2 is met, then the record will be sorted in ascending 
order. 

Figure 11-10 shows the result of using the previous sample specification file on 

an input file named BALANCES. LI S: 
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Figure 11-10 Output from Using a Specification File 


— BALANCES. LIS — 


— BALANCES_BYSIGN.LIS 

4124 


-3359 

-2355 


-2355 

2538 


-1744 

-3359 


2538 

3423 


3423 

-1744 


4124 

5264 


5264 
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11.5 Optimizing a Sort or Merge Operation 

There are several ways in which you might improve the efficiency of a sort or 
merge operation. You can view the variables in your sorting environment by 
using the /STATISTICS qualifier with the SORT or MERGE command. After you 
examine the statistics display, consider any of the optimization options presented 
in the following sections. 

When you enter the SORT or MERGE command with the /STATISTICS qualifier, 
you see output similar to the following: 

$ SORT/STAT PAGEANT. LIS DOCUMENT. LIS 


VAX Sort/Merge Statistics 


Records read: 

3 1 

Input record length: 

26 

Records sorted: 

3 

Internal length: 

28 

Records output: 

3 

Output record length: 

26 

Working set extent: 

16384 2 

Sort tree size: 

42 

Virtual memory: 

392 

Number of initial runs: 

0 

Direct I/O: 

10 

Maximum merge order: 

0 

Buffered I/O: 

11 

Number of merge passes: 

0 

Page faults: 

158 3 

Work file allocation: 

0 

Elapsed time: 00:00 

: 00 . 54 5 

Elapsed CPU: 00:00: 

: 00 . 03 


From this statistics display, you can determine: 

1 Records read 

Lists the number of records that were read during a sort operation. See 
Section 11.5.2 for information on selectively omitting records from a sort 
operation. 

2 Working set extent 

Shows how many blocks are reserved to perform the sort operation. See 
Section 11.5.4 for information on making your working set larger. 

3 Page faults 

Shows how many times the operating system has transferred parts of your 
process from physical memory to your paging device. See Section 11.5.4 for 
more information on preventing paging. 

4 Work file allocation 

Shows how much disk space is reserved for your work file. See Section 11.5.3 
for more information on work files. 

5 Elapsed time 
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Shows how much CPU time the operating system took to process the sort 
operation. See Section 11.5.1 for information on saving time by choosing 
different methods of sorting. 

For information on how a system manager can improve efficiency when using the 

Sort/Merge utility, see the OpenVMS System Manager's Manual. 

11.5.1 Improving Performance During Sorting 

In addition to record sorting, you can also perform the following types of sorting 

by using the appropriate qualifiers with the SORT or MERGE command: 

• Tag sorting (/PROCESS=TAG) 

Sorts the key fields only and then rereads the input file to produce an output 
file of complete records. The net result is the same as for a complete record 
sort. A tag sort is useful if disk space is low because it typically uses less 
workfile space during the sorting. I n most cases, a tag sort is slower than a 
record sort because it requires extra time to reread the input file. 

• Address sorting (/PROCESS=ADDRESS) 

Sorts the key fields only and produces an output file that is an index of 
record file addresses (RFAs) in binary format. An address sort is faster 
than a record sort but you must write a program to associate the record 
addresses with the records of the input file. 

• I ndexed sorting (/PROCESS^) NDEX) 

Sorts the key fields only and produces an output file of keys and RFAs (in 
binary format). As with an address sort, an index sort is faster than a record 
sort, but you must write a program to associate the record addresses with the 
records of the input file. 

Before you select a sorting process, consider the following: 

• Flow you will use the output file 

- Because record and tag sorting generate files containing entire sorted 
records, these reordered files are ready to be used. 

- Both address- and index-sorted output files can be processed by a program 
written in a programming language such as Pascal, FORTRAN, MACRO, 
or C. 

- Address sorting creates a list of pointers to the records in the input file. 
This list consists of binary RFAs plus a file number when sorting multiple 
input files. A program accesses the records by using the pointers. 

- I ndex sorting creates an output file containing both RFAs and key fields 
plus a file number when sorting multiple files. The format of these key 
fields is the same as in the input files. If the program needs the key 
field contents for a decision during future processing, select index sorting 
rather than address sorting. 

If you need to reorder records from one file in several ways for different 
purposes, store several output files from address or index sorting. Use the 
output files to access the records in the main file in the sorted order you 
want. 

• The temporary storage space available for sorting 
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Tag sorting uses less temporary storage space than record sorting. Because 
record sorting keeps the record intact during the sort, it uses much more work 
space when the files are large. Address and index sorting use little temporary 
storage space. 

• The type of input and output device used 

Record sorting is the only process that can accept input from cards, magnetic 
tape, and disk. Output from tag and record sorting can go to any output 
device. Output from address and index sorting must go to a device that 
accepts binary data. 

• The differences in speed 

If you plan to retrieve the sorted records at some point in the operation, 
record sorting is usually the fastest process. Otherwise, address and index 
sorting are the fastest processes. 

11.5.2 Selectively Omitting Records and Fields 

You can improve Sort efficiency by using a specification file. The /CONDITION, 

/I NCLUDE, and /OM IT qualifiers allow you to select the records needed in the 
output file. You can also use specification file qualifiers to reformat records, 
omitting unnecessary fields from the output file. 

For a description of these qualifiers, see Table 11-1. 

11.5.3 Assigning Sort Work Files to Different Devices 

During a sort operation, records from the input file are read into memory. 

If the allocated memory cannot hold all the records, Sort transfers sorted 
strings to a temporary work file. This is not true for a merge operation. Merge 
does not require the use of work files. The DCL command line qualifier for 
SORT/WORKFI LES=n overrides the number of work files allocated. The 
/WORK FI LES=(Device,...) qualifier within a Sort/Merge specification file will 
place the work files on the specified devices. 

You can increase Sort efficiency by assigning the location of the work files to 
random-access, mass storage devices such as disks. Normally, Sort places work 
files on the device SYS$SCRATCFI and accesses them in an arbitrary order. 

For greatest sorting efficiency, place work files on the fastest devices available. 
Choose devices with the least activity and the most space available. 

To select a different device for any Sort work file, use the DCL command ASSI GN, 
as follows: 

ASSIGN device: SORTWORKn 
The fields are as follows: 

device: The device that you want to place the work files on. For greatest 

sorting efficiency, place work files on the fastest device available. 

SORTWORK A logical name for the work files 

n The number of the work file. Acceptable values are 0 to 9. For 

example, if you specify /WO RK_F I LES=3, use the logical names 
SORTWORKO, SORTWORK 1, and SORTWORK2 to assign these three 
work files to other devices. For more information on logical names, see 
Chapter 13. 

For more information on the ASSIGN command, see the OpenVMS DCL 
Dictionary. 
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11.5.4 Modifying the Working Set Extent 

If Sort requires work files (for example, if you are sorting a large file), a larger 
working set might increase sort efficiency. However, if your system is used 
heavily, it might be unable to allocate all the pages in the working set extent 
to your process. Paging occurs when the operating system transfers parts of a 
process between physical memory and memory on a paging device, so only the 
active part of the process remains in the physical memory. To avoid excessive 
paging, you can decrease the working set extent for your process. (See your 
system manager.) 

11.6 Summary of Sort/Merge Qualifiers 

Table 11-1 summarizes qualifiers to the SORT and MERGE commands. These 
qualifiers define key fields, describe the data in those fields, and specify various 
Sort/Merge utility options. For more detailed information, refer to online help. 

Note that the /PROCESS and /WORK_FI LES qualifiers apply only to the SORT 
command and the/CHECK_SEQUENCE qualifier applies only to the MERGE 
command. 


Table 11-1 Summary of Sort/Merge Qualifiers 


Qualifier 

Default 

Command Qualifiers 1 


/[NO]CHECK_SEQUENCE 

(Applies to the MERGE command only.) Verifies the sequence 
of the records in MERGE input files. By default, the sequence 
of records is checked. 

/CHECK _SEQUENCE 

/COLLATI NG SEQUENCE =sequence 

Selects one of three predefined collating orders for character 
key fields, or specifies the name of a National character set 
(NCS) collating sequence to be used in comparing character 
keys. Sort can arrange characters in ASCII, EBCDIC, or 
Multinational sequences. 

/ COLLATI NG -SEQUENCE =ASCII 

/[NO]DU PL 1 CATES 

By default, all multiple records with duplicate keys are kept. 
The /NODUPLICATES qualifier eliminates all but one of 
multiple records with duplicate keys. 

/DUPLICATES 

/KEY=(POSmON:n,SIZE :n[, field,...]) 

Describes key fields, including the position, size, sorting order 
(ASCENDING or DESCENDING), priority (NUMBER:n), 
and data type (such as character, binary, h_floating). For a 
complete list of supported data types, refer to online help. 

By default, Sort reorders a file by sorting entire records with 
character data in ascending order. 

None 

/PROCESS^ype 

(Applies to the SORT command only.) Defines the internal 
sorting process. The /PROCESS qualifier allows you to choose 
one of four processes: record, tag, address, or index. 

/PROCESS=RECORD 


use a command qualifier, include the qualifier immediately after the SORT or MERGE command. 


(continued on next page) 
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Table 11-1 (Cont.) Summary of Sort/Merge Qualifiers 


Qualifier 

Default 

Command Qualifiers 1 

/SPECIFICATION=filespec 

1 dentifies a SORT or MERGE specification file to be used in a 
SORT or MERGE operation. 

None 

/[NO]STABLE 

By default, records with equal keys are not guaranteed to be 
placed in the output file in the order they appear in the input 
file. The /STABLE qualifier maintains the records in that 
order. 

/NOSTABLE 

/[NO]STATI STICS 

Displays a statistical summary that can be used for 
optimization. 

/NOSTATISTICS 

/WORK_FILES[=n] 

(Applies to the SORT command only.) Requests additional 
work files to be used for improving the efficiency of the sort 
operation (when disks lack sufficient space for large files, for 
example). 

/ WOR K_FI LES=2 

Input File Qualifier 2 

/FORMAT=(RECORD_SIZE:n,FILE_SIZE :n) 

Defines input file characteristics; allows you to specify or to 
override record size for OpenVMS RMS undefined file formats, 
or file size. 

1 nput file values 

Output File Qualifiers 3 

/ALLOCATIONS 

Specifies the number of blocks to be preallocated to the output 
file for optimization. Use this qualifier when you know that 
the output file allocation will differ substantially from the total 
input file allocation (for example, when reformatting data or 
omitting records). 

RMS defaults or input file values 

/BUCKET SIZE=n 

One (1) or input file values (if the 

Specifies OpenVMS RMS bucket size (the number of 512- 
byte blocks per bucket) to be used by relative and indexed 
sequential output disk files for optimization. 

organization is the same) 

/CONTIGUOUS 

Requests that the output file be stored in contiguous disk 
blocks to decrease access time. Must be used with the 
/ALLOCATION qualifier. 

None 


^To use a command qualifier, include the qualifier immediately after the SORT or MERGE command. 


2 To use an input file qualifier, include it immediately after the input file specification in the SORT or MERGE command 
line. 

3 To use an output file qualifier, include the qualifier immediately after the output file specification in the SORT or 
MERGE command line. 


(continued on next page) 
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Table 11-1 (Cont.) Summary of Sort/Merge Qualifiers 


Qualifier 

Default 

Output File Qualifiers 3 

/FORMAT =(type:n[,...]) 

Input file record format 

Specifies the output filerecord format (FIXED:n, VARIABLES, 
or CONTROLLED:n) if it differs from the input file format. 

You can also specify the size (SIZE:n) or the block size 
(BLOCK_SIZE:n) of the file records. 


H NDEXE D SEQUE NTIAL 

None 

Defines the file organization for the output file as indexed 
sequential. Note that the output file must already exist and 
must be empty. 1 n addition, you must specify that the empty 
file is to be overlaid with the sorted records by using the 
/OVERLAY qualifier. 


/OVERLAY 

None 

Specifies that the output file is to be overlaid on, or written to, 
an existing empty file. 


/RELATIVE 

None 

Defines the file organization for the output file as relative. 

/SEQUENTIAL 

Defines the file organization for the output file as sequential. 

None 


Specification File Qualifiers 4 

/CDD_PATH_NAME="cdd-path-name" 

None 

Allows use of the CDD/Repository record definitions. Can only 
be used on a system with CDD/Repository installed. 


/[NO]CHECK_SEQUENCE 

/ CHECK_SEQUENCE 

(Applies to the MERGE command only.) Specifies whether or 
not the sequence of records is checked. 


/COLLATI NG SEQUENCE = 

(SEQUENCE sequence-type 
[,MODIFICATION=("charl" operator "char2")] 

[, IGNORE character or character range,...] 

[.FOLD] 

[,[NO]TIE BREAK]) 

/COLLATING SEQUENCE = 
(SEQUENCE =ASCII, NOTIE_BREAK) 

Specifies one of three predefined collating sequences (ASCII, 
EBCDIC, or Multinational) or a user-defined sequence 
for character key fields. Allows you to modify any of the 
predefined collating sequences or any previously defined 
user-defined sequences. 



3 To use an output file qualifier, include the qualifier immediately after the output file specification in the SORT or 
MERGE command line. 

4 Specification file qualifiers are valid only within a Sort/Merge specification file. 


(continued on next page) 
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Table 11-1 (Cont.) Summary of Sort/Merge Qualifiers 


Qualifier 

Default 

Specification File Qualifiers 4 


/CONDITION = 

(NAME =conditi on-name, 

TEST =(field-name operator test-condition 
[logical-operator...])) 

Defines conditions for key and data handling and for record 
selection. 

None 

/DATA=field-name 

/DATA=(I F condition THEN "new contents" 

ELSE "new contents") 

Specify the fields of a record to be directed to the output file. 

None 

/FIE LD=(NAME =field-name,POSITI ON:n,SI ZE :N, 

[ D 1 G 1 T S :n,]data-ty pe) 

Defines the name, position, and size of the fields in the input 
files. 

None 

/INCLUDE=(CONDITION=condition[,KEY^..] 

[,DATA^..]) 

Specifies record selection as well as multiple record formats. 

None 

/KEY=field-name 

/KE Y =(fiel d-name, order ) 

/KEY=([IF condition THEN value ELSE]...) value [.order] 

Specify the key fields to be used in the sort operation. If you 
are sorting the entire record using character data, there is no 
need to specify your key field. 

None 

/OMIT=(CONDITION=condition-name) 

Specifies record selection as well as multiple record formats. 

None 

/PAD single-character 

Specifies the character Sort will use to expand, or "pad," a 
string when reformatting records or when comparing strings of 
unequal length. 

/ PAD—'" 

/PROCESS=type 

(Applies to the SORT command only.) Defines the processing 
method (record, tag, address, or index) for the sorting 
operation. If you intend to reformat the output records, you 
cannot use address or index sort. 

/ PROCESS=RECORD 

/[NO]STABLE 

Specifies that records with equal keys are directed to the 
output file in their input file order. 

/NOSTABLE 

/WORK_F 1 L E S=(device[,...]) 

(Applies to the SORT command only.) Specifies the 
reassignment of work files. By placing work files on different, 
disk-structured devices, you can i mprove the performance of 
Sort. 

None 

Specification file qualifiers are valid only within a Sort/Merge specification file. 
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If all the files you create and use are located on devices managed by a system 
manager, you might not need to learn how to access a tape or disk drive. The 
system manager can set up logical names to refer to the devices you need to 
use. You can then read, write, and copy files to and from the device by using the 
logical name. I n most cases, the system manager sets up and maintains devices 
that are shared by a group of users. 

However, if you have a tape or disk drive available for your private use (for 
example, if your workstation includes an integral tape or diskette drive), you 
should be familiar with a few commands for accessing those devices. Diskettes 
and diskette drives are one type of disk device. For simplicity, this chapter uses 
the generic term disks to refer to all types of disks. 

Note 

Although a disk or tape is for your exclusive use, anyone with physical 
access to it can read its contents on some system. It is good practice to 
keep disks and tapes in a safe place and to erase sensitive data before 
recycling them so the next user cannot read their contents. 


I n this chapter, storage media is sometimes referred to as volumes. While the 
storage media itself is a piece of hardware, you can think of it in terms of its 
stored data; a volume is a disk or tape that has an organized collection of data. 

To perform your work on a device that cannot be accessed by other users, you can 
create a private volume and mount it on a device allocated exclusively for you. 
The steps for setting up a private volume are as follows: 

1. Use the DCL command ALLOCATE to assign the device (disk or tape) drive 
to your process. 

2. Use the DCL command I NITIALIZE to format the disk or tape volume and 
write an identifying label on the volume. 

3. Use the DCL command MOUNT to make a volume and the files or data it 
contains accessible to your process. 

This chapter describes how to allocate, initialize, and mount a device for private 
use. For more information on the ALLOCATE and INITIALIZE commands, 
see the OpenVMS DCL Dictionary. For a complete description of the MOUNT 
command, see the OpenVMS System Management Utilities Reference Manual . 
Additional information is also available through DCL Help. 
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12.1 Displaying Device Information 


To display information about volumes that are on your 
DEVICES command, as follows: 

$ SHOW DEVICES 


Device Device 

Name Status 

DMA2 : Mounted 

MTA1 : Online 


Error Volume 
Count Label 

0 BACKUP_FILE 

0 


system, enter the SHOW 


Free Trans Mnt 
Blocks Count Cnt 
4442 7 1 


To obtain more information or information about a specific device, enter the 
SHOW DEVICES command in one of the following ways: 

• To check the densities, volume labels, UlCs, and relative volume numbers of 
mounted volumes, enter the SHOW DEVICES/FULL command. 

• To display information for all the drives of a particular type configured in the 
system, specify a generic device code for magnetic tape drives (such as MT). 

• To display information for a volume mounted on a specific drive, specify the 
physical device name (for example, MTA1:). 

12.2 Allocating a Device 

Before you can use files or data on a private volume, you must allocate (locally 
assign) a disk or tape drive to your process with the DCL command ALLOCATE. 
The format for the ALLOCATE command is as follows: 

ALLOCATE device-name[:] [logical-name] 

The elements are as follows: 

device-name Specifies the drive on which the volume is loaded. The name can be a 
physical name, a generic name, or a logical name. 

logical-name Specifies an optional logical name to be associated with the device. 
Table 12-1 summarizes the ways in which you can allocate a device. 


Table 12-1 Allocating a Device 

Example Explanation 


To allocate a specific physical device: Uses a physical device name (DM B2) to request the 

allocation of a specific RK06 or RK07 disk drive (unit 2 
$ ALLOCATE DMB2 : on controller B). 

%DCL-I-ALLOC, _MARS$DMB2 : allocated 


To allocate the first available device: 

$ ALLOCATE DM: DISK 
%DCL-I-ALLOC, _MARS$DMB1: allocated 


Uses the generic device code DM to allocate the first 
available RK06 or RK07 disk device. In addition, 
creates the logical name DISK in the process logical 
name table and assigns it to the name of the allocated 
device. 


(continued on next page) 
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Table 12-1 (Cont.) Allocating a Device 


Example 

Explanation 

To allocate a device by logical name: 

$ ALLOCATE DRIVEl: D1 
%DCL-I-ALLOC, _MARS$DBA3 : allocated 

Allocates DRIVEl (a logical name that translates to 
the physical device DBA3) and assigns a new logical 
name D1 to the allocated device. 

To select a particular device type: 

$ ALLOCATE/GENERIC RK07 MYDISK 

Uses the /GENERIC qualifier to allocate a particular 
type of device (an RK 07 disk). 

To specify a list of generic devices: 

$ ALLOCATE MF,MT,MS DRIVE 
%DCL-I-ALLOC, _MARS$MTA0 : allocated 

Specifies a list of generic device names; the first 
available device (MTAO) is the only one to be allocated. 

1 n addition, assigns the logical name DRIVE to MTAO. 

The ALLOCATE command allocates only one device to 
a process. Therefore, although each element in the list 
represents a unique, generic device type, only one of 
the specified generic devices is allocated. 


When you allocate a device, you reserve the device for exclusive use by your 
process. The device remains allocated to your process until you explicitly 
deallocate it (with the DCL command DEALLOCATE) or until you log out. 

12.3 Initializing a Volume 

I nitializing a disk or tape volume allows you to write files to that disk or tape. 

Note 

The INITIALIZE command does not prevent you from initializing another 
user's volume; to be sure the volume you initialize is your own, allocate 
the device before you initialize the volume. 


To initialize a volume, use the DCL command I NITI ALIZE, which does the 

following: 

• Deletes (erases) all existing data on the volume, if any, and creates a new file 
structure 

• Writes a label on the volume to identify it 

• Defines the owner UIC and the protection for the volume 

The format for the INITIALIZE command is as follows: 

INITIALIZE device-name[:] volume-label 

The fields are as follows: 

device-name Specifies the name of the device on which the volume is physically 
mounted. 

volume-label Identifies the volume. You can specify up to 12 alphanumeric 

characters for a disk volume or up to 6 alphanumeric characters 
for a magnetic tape volume. 
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If you give a volume to another user for initialization (for example, if you lack 
sufficient privileges to initialize a particular volume), you should provide the 
volume label, the owner UIC, and the protection code for the volume. 

The following sections provide examples for initializing disks and tapes. 

Initializing a Disk Volume 

By default, the INITIALIZE command builds a Files- 11 structure on your 
new volume. The default format for disk volumes initialized for or by the 
OpenVMS operating system is called the Files- 11 On-Disk Structure Level 2. 
The I NITI ALIZE command can also initialize disk volumes in Files- 11 On-Disk 
Structure Level 1. 

You do not need special privileges to override logical protection on a blank disk 
volume (that is, a volume that has never been written to) or on a disk volume 
that is owned by your current UIC or by UIC [0,0], In all other cases, you must 
have user privilege VOLPRO to initialize a disk volume. 

The following example initializes the volume on DMA1 and labels the volume 
ACCOUNTS: 

$ INITIALIZE DMA1: ACCOUNTS 

Initializing a Magnetic Tape Volume 

The default format for magnetic tape volumes produced by the I NITI ALIZE 
command is based on Level 3 of the American National Standards Institute 
(ANSI) X3. 27-87 and International Standards Organization (ISO) standards for 
magnetic tape labels and file structure for informational interchange. 

If you use ANSI "a" characters (which are not alphanumeric) on the volume label 
on magnetic tape, you must enclose the volume name in quotation marks. 

The following example initializes the volume on MTB1 and labels the volume 
SOURCE: 

$ INITIALIZE MTB1 : SOURCE 

12.4 Mounting a Volume 

Before you attempt to use files or data on an allocated disk or tape volume, make 
sure the volume is mounted. The DCL command MOUNT makes a volume and 
the files or data it contains accessible to your process. 

When you enter the MOUNT command, the system verifies that the following 
conditions have been met: 

• The device has not been allocated by another user. 

• The device protection allows you to allocate the device. 

• A volume is physically loaded on the specified device. 

• The label on the volume matches the label you specified. 

You can mount a single volume or a volume set. Binding volumes into a volume 
set allows you to extend the space available for your files by adding volumes to 
the same set, rather than by defining multiple, new volumes. The procedures for 
creating and mounting volume sets (as opposed to single volumes) are described 
in the OpenVMS System Manager's Manual. 
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The MOUNT command format is as follows: 

MOUNT device-name[:][,...] [volume-label[,...]] [logical-name[:]] 

The elements are as follows: 

device-name Specifies the physical device name or logical name of the device on 
which the volume is to be mounted. 

volume-label Specifies the label with which the volume was initialized. You 
do not need to specify the volume label if you use one of the 
following MOUNT qualifiers: /FOREIGN, /NOLABEL, or 
/OVERRIDE IDENTIFICATION. 

logical-name Defines a name to be associated with the device. If you omit the 

logical name, the MOUNT command assigns the default logical names 
DISK$volume- label and TAPE$volume-label to disk and tape drives, 
respectively. 

Requesting Operator Assistance 

Operators can perform the physical mounting (and dismounting) of both system 
and private volumes. The following MOUNT command notifies the operator of 
your mount request and displays a message at your terminal: 

S MOUNT DMA1 : DISK V0L1 

%M0UNT-I-0PRQST, PLEASE MOUNT DEVICE _MARS$DMA1 : 

After the device has been successfully mounted, you are notified with the 
following message: 

%M0UNT- I -MOUNTED, DISK mounted on _DMA1 : 

MOUNT messages are sent to all operators enabled to receive TAPE and DISK 
messages. Thus, if operator assistance is needed for mounting a disk device, a 
message is sent to disk operators. 

If no operator is available (operator is not enabled) to receive and respond to a 
MOUNT request, a message is displayed to inform you of the situation. A volume 
placed in the requested drive needs no additional operator assistance. Note that 
you can specify the /NOASSI ST qualifier to avoid operator assistance. 

Mounting a Disk Volume 

The following example shows how to allocate, initialize, and mount a disk volume: 

$ ALLOCATE DMA2 : TEMP 
%DCL-I-ALLOC, _MARS$DMA2 : allocated 
$ INITIALIZE TEMP: BACKUP_FILE 
$ MOUNT TEMP: BACKUP_FILE 

%M0UNT- I -MOUNTED, BACKUP_FILE mounted on _DMA2 : 

$ CREATE/DIRECTORY TEMP : [ARCHIE] 

Before you can place any files on the volume, you must create a directory, as 
shown by the CREATE/DI RECTORY command in the previous example. 

Mounting a Foreign Disk Volume 

To mount a foreign disk volume (that is, one having a file structure other than 
Files- 11), use the /FOREIGN qualifier. For example: 

$ MOUNT/FOREIGN DISK 

%M0UNT-I-M0UNTED, BACKUP_FILE mounted on DISK$DMA2 : 
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The MOUNT/FOREIGN command makes the contents of your volume available 
to the system but makes no assumptions concerning its file structure. In the 
preceding example, MOUNT reports a volume label, indicating that the disk has 
a Files- 11 structure, even though it was mounted as a foreign device. If a disk 
does not have a recognized file structure, MOUNT does not display a label. 

Note that you need the user privilege VOLPRO to mount a Files- 11 structured 
disk with the /FOREI GN qualifier, unless its owner UIC matches your own. 

Mounting a Magnetic Tape Volume 

When you use the MOUNT command to mount a magnetic tape volume, the 
system checks to see whether the volume has an ANSI -labeled format. If the 
format is AN SI -labeled, MOUNT checks the following: 

• The volume identifier field 

• The protection on the AN SI -labeled volume 

The following command mounts an ANSI-labeled volume and assigns a logical 
name to it: 

$ MOUNT MT: SYSTPV ET 

%MOUNT-I-OPRQST, please mount volume SYSTPV in device $MTA1 : 

%M0UNT - I -MOUNTED , SYSTPV mounted on MTA1 : 

%M0UNT-I-RQSTD0N, operator request canceled — mount completed successfully 

MOUNT finds an available MT drive, MTA1, and requests operator assistance. 
The message displayed indicates which drive has been selected. At this point, you 
(or the operator) load the magnetic tape on the drive and the mount operation 
completes. No operator response is necessary. The display informs you that 
the volume named SYSTPV is mounted on the drive MTA1. Although MOUNT 
does not require a logical name, this example assigns the logical name ET to the 
volume SYSTPV. 

12.5 Accessing Files on Private Devices 

To access a file that is on a private device, you must either specify the device 
name or use the SET DEFAULT command to set default to the device. For files 
on disks, you must also specify the directory name. 

You can use physical, logical, or generic names described in the following sections 
to refer to devices. In addition, if your system is part of a VMScluster, certain 
devices are accessible to all members of the VMScluster. Section 12.5.4 describes 
the syntax for VMScluster device names. 

12.5.1 Using Physical Device Names 

Each physical device known to the system is uniquely identified by a physical 
device name. The physical device name identifies the kind of device; for 
example, a storage disk or a terminal. 

Most physical device names consist of: 

• A device code, which represents the hardware device type 

• A controller designator, which identifies the hardware controller to which the 
device is attached 

• A unit number, which identifies a device on a particular controller. 

For information on specific device-naming formats, see OpenVMS System 
Manager's Manual. 
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When a disk or tape is mounted on a device, the system recognizes it as a volume. 
The system also recognizes volume sets. A volume set consists of two or more 
related volumes. To access a file on a tape volume set, specify any device that has 
been allocated to it. 

To access a file on a disk volume set, you have the following options: 

• Specify the name of the device on which the first volume in the set is 
mounted. 

• Specify the logical name that was assigned to the volume set when it was 
mounted. 

If you do not specify a device name, the system supplies the current default device 
name. For more information on volumes and volume sets, see the OpenVMS 
System Manager's Manual. 

Some commands accept output file specifications. You can replace an output file 
specification with the name of a record-oriented device such as a printer or a 
terminal. For example: 

$ COPY DISFILE.DAT TTB4 : 

The COPY commandsendsthefileDISFILE.DAT to the terminal named TTB4. 
The terminal accepts and displays the file one record at a time. When you use a 
device name as a file specification, follow the device name with a colon (:). 

12.5.2 Using Logical Device Names 

Your system manager can set up logical device names to represent the devices 
on your system. Logical device names equate a somewhat cryptic device name to 
a short, meaningful name. You can use these logical device names, rather than 
the physical device names, to refer to devices. 

When you use a logical device name in a file specification, follow it with a colon. 
For example: 

$ TYPE C0D1: [NOAH] ANIMALS. LIS 

COD1 is a logical device name for the device that contains the disk volume with 
the file [NOAH ]ANI MALS.LI S. As long as the system manager defines the logical 
name COD1 correctly, the system can access the file, regardless of where the 
volume is mounted. 

Chapter 13 describes in more detail how to use logical names. 

12.5.3 Using Generic Device Names 

A generic device name consists of the device code and omits the specific 
controller or unit number. When you use a generic device name with the MOUNT 
or ALLOCATE commands, the system locates the first available controller or 
device unit whose physical name satisfies the portions of the generic device name 
you specified. 

If you specify a generic device name for any other command, the following 
defaults apply: 

• If you omit the controller designation, it is assumed to be A. 

• If you omit the unit number, it is assumed to be 0. 
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12.5.4 Using VMScluster Device Names 

A VMScluster device name includes the name of the node to which the device 
is attached and the physical device name, separated by a dollar sign ($). For 
example, ROXXY $DU A1 refers to disk DU A1 on node ROXXY. 

If a device is dual pathed (connected to two nodes), specify the VMScluster device 
name in the following format: 

$allocation-class$ddcu 

The elements are: 

allocation-class A value assigned to the nodes connecting a dual-pathed device. For 
example, $1$DJ A16 identifies a disk that is dual pathed between two 
nodes that both have an allocation class value of 1. 

dd Represents device code of the hardware device type (for example, the 

device code DK represents an RZ23 disk). 

c Identifies the hardware controller to which the device is attached. 

The controller designation, along with the unit number, identifies the 
location of the device within the hardware configuration of the system. 
Controllers are designated with alphabetic letters A to Z. 

u Uniquely identifies the unit number of a device on a particular 

controller. Unit numbers are decimal numbers from 0 to 65535. 

As a general rule, always use an allocation class device name to identify dual- 
pathed VMScluster disks. It is the only name that all VMScluster nodes recognize 
at all times. 

For more information on the device name format in VAXcluster or VMScluster 
environments, see VMScluster Systems for OpenVMS. 

12.6 Printing Files from a Private Device 

Although you can print a file from a privately owned volume, the volume 
containing the file to be printed must remain mounted until after the file has 
completed printing. If you want to dismount the volume before the file is done 
printing, copy the file directly to the printer. For example: 

$ COPY MYPHILE.DAT LPAO : 

12.7 Dismounting a Volume 

When you are done with the files on a disk or tape volume, you can use the 
DISMOUNT command to dismount the volume. Before a volume is dismounted, 
the DISMOUNT command checks for conditions that could prevent the dismount 
from completing. For example, if the volume contains installed swap and page 
files, installed images, or open user files, DISMOUNT displays an error message 
indicating that the volume cannot be dismounted. 

By default, the Dl SMOUNT command automatically unloads the volume from the 
drive. If you plan to mount or initialize a volume again after you dismount it, you 
can save time and eliminate unnecessary handling of that volume by using the 
/NOUN LOAD qualifier. For example: 

$ DISMOUNT/NOUNLOAD MTA1 : 

In this example, the magnetic tape volume is logically dismounted and the tape is 
rewound but the tape remains physically loaded on drive MTA1. 
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You should always explicitly dismount a volume with the DISMOUNT command 
before physically unloading the volume. Wait for the drive to unload before you 
remove the volume. (You can verify that the dismount is complete by entering the 
DCL command SHOW DEVICES.) 

A volume is dismounted and unloaded automatically if you log out of the job from 
which you had mounted the volume. If the system fails, however, the volume is 
not automatically dismounted. 

If the device you are dismounting was allocated with an ALLOCATE command, 
it remains allocated after it is dismounted with the DISMOUNT command. If 
the device was implicitly allocated by the MOUNT command, the DISMOUNT 
command deallocates it. 
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Logical Names: Defining Names for Devices 

and Files 


A logical name is a name that can be used in place of another character string to 
represent system objects such as files, directories, devices, or queues. The name 
is equated to a string (called an equivalence string or equivalence name) or a list 
of equivalence strings (called a search list). When you use a logical name, the 
equivalence string is substituted for the logical name. 

Logical names can be shorthand for long file specifications. For 
example, if you create the logical name COMS to represent the directory 
Dl SK7:[WALSH .COM MAN D_PROC], you can enter COMS in a DCL command 
line, such as the following: 

$ TYPE COMS : PAYROLL . COM 
$ SET DEFAULT COMS 

You can also use logical names to keep programs and command procedures 
independent of physical file specifications. For example, if a command procedure 
references the logical name ACCOUNTS, you can equate ACCOUNTS to any file 
on any disk before executing the command procedure. 

In general, when a command accepts a system object, the command checks 
whether the name you provide is a logical name. If the name is a logical name, 
the system replaces the logical name with its actual value and executes the 
command. 

Logical names can be defined by you or by the system. This chapter describes 
how to create and use logical names. It also discusses logical names created by 
the system. 

13.1 Using System-Defined Logical Names 

The system creates a set of systemwide logical names for you when you start the 
system and log in. These logical names allow you to refer to commonly used files 
or devices without using their physical device names. For example, to list your 
operating system's programs, you do not need to know the name of the disk and 
directory where these programs are stored. I nstead, you can use the logical name 
SYS$SYSTEM, as follows: 

$ DIRECTORY SYS$SYSTEM 

Every time you log in, the system creates a group of logical names for your 
process and places these names in your process table. For example, the logical 
name SYS$LOGI N refers to your default device and di rectory when you log in. If 
you have changed your current defaults by using the SET DEFAULT command, 
you can use the following command to display a file from your initial default 
directory: 

S TYPE SYS$L0GIN: DAILY_NOTES.DAT 
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13.2 Creating Logical Names 

You can create logical names with either the ASSIGN command or the DEFINE 
command. Usually, you define logical names in a login command procedure 
(LOGIN.COM), so you can use the logical name each time you log in. You can 
also create logical names interactively. However, you can use these logical names 
only while your current process is active. Your system manager can create logical 
names for use by anyone logged in to the system. 

The following sections describe how to use the DEFI NE command to create logical 
names. N ote that the format for the DEFINE command differs from the format 
for the ASSIGN command. For information on using the ASSI GN command, 
enter the HELP ASSIGN command or refer toth eOpenVMS DCL Dictionary. 

13.2.1 Using the DEFINE Command 

The format for defining a logical name with the DEFI NE command is as follows: 
DEFINE logical-name equivalence-string[,...] 

For example, the following command creates the logical name WORKFI LE 
and equates it the equivalence string Dl SK2:[WALSH ,REPORTS]WORK_ 
SUMMARY.DAT: 

$ DEFINE WORKFILE DISK2 : [WALSH. REPORTS iWORK_SUMMARY.DAT 

After you define WORKFI LE as a logical name, you can use the logical name 
interchangeably with the equivalence string. 

The same format can be used to create logical names for other system objects. 

For example, the following command creates the logical name MY_Q for the print 
queue BLDGC_LPS20_ANSI : 

$ DEFINE MY_Q BLDGC_LPS20_ANSI 

You could then use the following command to print the file FABLES.TXT to the 
BLDGC_LPS20_ANSI print queue: 

$ PRINT/QUEUE=MY_Q FABLES.TXT 

13.2.2 Rules for Creating Logical Names 

Observe the following rules when you create a logical name with the DEFINE 
command: 

• Limit the equivalence string and the logical name to no more than 255 
characters each. A logical name can contain alphanumeric characters, the 
underscore (_), the dollar sign ($), and the hyphen (-). 

• When you specify an equivalence string, include the punctuation marks 
(colons, brackets, periods) required by a file specification. For example, end 
a device name with a colon, enclose a directory specification in brackets, and 
precede a file type with a period. 

• If a logical name represents only part of a file specification, separate the name 
from the rest of the file specification with a colon. When you use a logical 
name to represent a complete file specification, the terminating colon is not 
needed. 
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In addition, be sure the logical name is the leftmost component of a 
file specification. For example, the following commands display the file 
Dl SKI: [SAL ES_STAFFpAYROLL.DAT: 

$ DEFINE PAY DISKI : [SALES_STAFF] PAYROLL .DAT 
$ TYPE PAY 

$ DEFINE PAY_FILE DISKI : [SALES_STAFF] PAYROLL 
$ TYPE PAY_FILE : * .DAT 

$ DEFINE PAY_DIR DISKI: [SALES_STAFF] 

$ TYPE P AY_D I R : PAYROLL . DAT 

$ DEFINE PAY_DISK DISKI : 

$ TYPE PAY_DISK: [SALES_STAFFIPAYROLL.DAT 

• Optionally, end the logical name with a colon. 

Note 

The ASSIGN command removes the colon before placing the logical name 
in a logical name table; the DEFINE command saves the colon as part of 
the logical name. 


• If you equate a logical name to one equivalence string, then equate the same 
logical name to a different equivalence string, the second definition will 
supersede the first, unless you define them in different logical name tables 
or define them with different access modes. 

By default, the DEFINE command places logical names in your process logical 
name table, where the logical name is available only to your process and 
subprocesses. Section 13.3 describes logical name tables. 

13.2.3 Creating Logical Node Names 

You can use a logical node name in place of a network node name or in place of 
a node name and an access control string. Once you define a logical node name, 
you can use it to avoid typing (and displaying) your user name and password on 
the screen. 

To define a logical node name, observe the following rules: 

• Do not begin the logical name with an underscore (_). 

• End the equivalence string with a double colon ( :: ) and enclose it in quotation 
marks ( " "). 

• Use two sets of quotation marks ( "" "") where you want quotation marks to 
appear in the access control string. 

• Specify a logical name that contains 1 to 255 characters. 

For example, the following command equates the logical name BOS to the node 
name BOSTON and an access control string, where ADAMS is the user name and 
OLM EKI KA is the password: 

$ DEFINE BOS "BOSTON” "ADAMS OLMEKIKA" " : : " 
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Caution 

Do not place a DEFINE command that includes a password in a file (your 
login command procedure, for example). If others read the file, they will 
see the password. 


Using Logical Node Names in File Specifications 

A file specification can contain both a logical node name (which the system 
translates at the local node) and a logical device name (which the system 
translates at the remote node). For example: 

$ DEFINE NYC NEWYRK: : 

$ TYPE NYC: : DOC: [PERKINSJTERM_PAPER.DAT 

In this example, the system translates the logical node name NYC at the local 
node. It translates the device name (DOC:) at the remote node (NEWYRK). If you 
use a logical name to represent a node name only, you must include a double colon 
(::) when you use the logical name in the node position of a file specification. 

After the system translates a logical node name at the local node, it parses the 
rest of the file specification to determine whether the format is valid. 

Overriding the Access Control String in a Logical Node Name 

To override the access control string in a logical node name, specify both the 
logical name and an access control string in the command line. For example: 

$ DEFINE BOS "BOSTON" "ADAMS OLMEKIKA" " : : " 

$ TYPE BOS"REVERE HTEBAZILE" :: RIDE . DAT 

In this example, the access control string "REVERE FITEBAZILE" overrides the 
access control string given in the equivalence string for BOS. 

When the system translates a logical node name iteratively, the access control 
information in the logical node name that is translated first overrides following 
access control information. For example: 

$ DEFINE TORONTO "TRNTO" "TEST EIZNEKCAM" " : : " 

$ DEFINE TEST1 "TORONTO" "TEST NAMWENLUAP" " : : DBA1 : " 

$ TYPE TEST1 : PR0C.DAT 

In this example, the logical nameTESTl translates to TORONTO'TEST 
NAMWENLUAP"::DBA1:. TORONTO is a logical node name, so iterative 
translation occurs. I n other words, the operating system searches the logical 
name tables until all levels of logical names in a definition are found. Flowever, 
the access control string in the DEFINE TEST1 logical name assignment 
overrides the access control string in the DEFINE TORONTO logical node name 
assignment. Therefore, the TYPE command displays the following file: 

TRNTO "TEST NAMWENLUAP": : DBA1 : PROC . DAT 

13.2.4 Creating Concealed and Terminal Logical Names 

When you create a logical name, you can specify translation attributes that 
modify how the system interprets the equivalence string. 

The CONCEALED attribute causes system messages to display the logical name 
rather than the physical name of a device. Typically, you use the CONCEALED 
attribute with logical names that represent physical devices. Using concealed 
devices lets you write programs, write command procedures, and perform other 
operations without being concerned about which physical device holds the disk 
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or tape. It also lets you use names that are more meaningful than the physical 
device names. 

The TERM INAL attribute prevents iterative translation of a logical name (that 
is, the equivalence string is not examined to see if it is also a logical name). The 
translation is "terminal" (final or completed) after the first translation. 

To apply these two translation attributes to an equivalence string, use the 
ATRAN SL ATI ON_ATTRI BUTES qualifier to the DEFINE command. This is a 
positional qualifier: depending on where you place it on a command line, it can 
apply translation attributes to all equivalence strings or only to certain ones. For 
example, to conceal the device name DJ A3: with the logical name DISK, enter 
the foil owing command: 

$ DEFINE/TRANSLATION JlTTRIBUTES=CONCEALED DISK DJA3 : 

$ SHOW DEFAULT 
DISK: [SAM. PUP] 

$ SHOW LOGICAL DISK 

"DISK" = "DJA3" (LNM$PROCESS_TABLE) 

The logical name DISK represents the physical device DJ A3. Thus, the SHOW 
DEFAULT command displays the logical name DISK rather than the physical 
device name, DJ A3. The SHOW LOGICAL command reveals the translation of 
DISK. 

13.2.5 Equating Several Logical Names to One Equivalence String 

You can equate more than one logical name to an equivalence string by entering 
more than one DEFINE command. For example, the following commands 
equate the logical names $TERMI NAL and CONSOLE to the physical name of a 
terminal so that both logical names translate to the same device (LTA69): 

$ DEFINE $TERMINAL LTA69 
$ DEFINE CONSOLE LTA69 

13.2.6 Creating a Search List 

To create a search list, equate a logical name to more than one equivalence string 
in a single command. I n the following example, the logical name GETTYSBURG 
is a search list: 

$ DEFINE GETTYSBURG [JONES . HISTORY] , [JONES .WORKFILES] 

$ SHOW LOGICAL GETTYSBURG 

"GETTYSBURG" = " [JONES .HISTORY] " (LNM$PROCESS_TABLE) 

= " [JONES. WORKFILES] " 

When you use a search list, the system translates the logical name until it finds 
a match. The order in which you specify the equivalence strings determines the 
order in which the system translates the names. It uses each equivalence string 
listed in the definition until a match is found. 

A search list is not a wildcard. It is a list of places to look. Once a file is found, 
the search ends. I n the following example, the TYPE command searches the 
equivalence string [J ONES.H I STORY] before it searches [J ONES.WORKFI LES] 
(the order specified in the preceding logical name definition for GETTYSBURG): 
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$ TYPE GETTYSBURG: SPEECH. TXT 
DISKI : [JONES . HISTORY] SPEECH . TXT; 2 

Fourscore and seven years ago, our fathers brought forth on 
this continent a new nation, conceived in liberty, and 
dedicated to the proposition that all men are created equal. 


Once the TYPE command finds a file named SPEECH.TXT, it ends the search 
and displays the file. 

You can use a search list with a command that accepts wildcards. When you use 
wildcards, the system forms file specifications by using each equivalence string in 
the search list. The command operates on each file specification that identifies an 
existing file. 

For example, if you specify the Dl RECTORY command with a wildcard character 
in the version field, it finds all versionsofSPEECH.TXT in the search list defined 
by GETTYSBURG, as shown in the following example: 

$ DIRECTORY GETTYSBURG: SPEECH . TXT; * 

Directory DISKI : [JONES .HISTORY] 

SPEECH. TXT;2 SPEECH.TXT; 1 

Total of 2 files. 

Directory DISKI: [ JONES .WORKFILES] 

SPEECH.TXT; 1 
Total of 1 file. 

Grand total of 2 directories, 3 files. 

When you enter a search list (for example, using the DIRECTORY command), the 
operating system uses elements in one part of the list to supply parts of the file 
specification that are omitted from other parts of the list. If a file specification 
is not precise (as shown in the following example), command lines can produce 
multiple files and file-not-found conditions: 

$ DIRECTORY SYS$MANAGER: LOGIN . COM, SYS$L0GIN 

You can avoid producing multiple files and file-not-found conditions by placing a 
semicolon after the file specification, as shown: 

$ DIRECTORY SYS$MANAGER: LOGIN . COM; , SYS$L0GIN 

13.2.7 Using Different Logical Name Tables 

Identical logical names can exist in more than one logical name table (see 
Section 13.3). The logical name that the system uses depends on the order 
in which it searches the logical name tables. For example, when the system 
attempts to translate a logical name to identify the location of a file, it uses the 
logical name LNM$FILE_DEV to provide the list of tables in which to look for the 
name. The order in which the tables are listed is also the order in which they are 
searched. 

By default, the precedence order defined by LNM$FI LE_DEV is: 

1. Process table 

2. J ob table 
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3. Group table 

4. System table 

So, for example, if a logical name exists in both the process and the group logical 
name tables, the logical name within the process table is used. See Section 13.3.3 
for information about redefining LNM$FI LE_DEV. 

By default, the DEFINE and DEASSIGN commands place names in, and delete 
names from, your process table. Flowever, you can request a different table with 
the /TABLE qualifier. For example: 

$ DEFINE/TABLE=LNM$SYSTEM REVIEWERS DISK3 : [PUBLIC] REVIEWERS . DIS 

This command creates the logical name REVI EWERS in the system table. 

13.2.8 Using Different Access Modes 

The OpenVMS operating system has four access modes, as follows: 

• User mode (the outermost and least privileged mode) 

• Supervisor mode 

• Executive mode 

• Kernel mode (the innermost and most privileged mode) 

You can usetheDCL commands DEFINE or ASSIGN to create logical names in 
the first three modes (user, supervisor, and executive). By specifying different 
access modes for each logical name definition, you can equate the same logical 
name to different equivalence strings in the same logical name table. For 
example, the following commands equate the logical name ACCOUNTS to two 
different equivalence strings in the process logical name table— one in supervisor 
mode and one in executive mode: 

$ DEFINE ACCOUNTS DISKI : [ACCOUNTS] CURRENT . DAT 

$ DEFINE/EXECUTIVE_MODE ACCOUNTS DISKI : [JANE .ACCOUNTS] OBSOLETE . DAT 

When you use the DEFI NE command without specifying a mode, DCL creates the 
logical name in supervisor mode. 


Note 

You must have SYSNAM or SYSPRV privileges to create logical names in 
executive mode in any logical name table. 


Defining Logical Names in User Mode 

Logical names created in user mode are temporary. Define a logical name in 
user mode when you want to use it only for the execution of the next command 
or image. In the following example, the logical name ADDRESSES is deleted 
automatically after the execution of the program PAYABLE: 

$ DEFINE/USER_MODE ADDRESSES DISKI : [SAM. ACCOUNTS] OVERDUE . LIS 
$ RUN PAYABLE 
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Defining Logical Names in Executive Mode 

In looking up logical names, all privileged images and utilities, such as 
LOGIN OUT and Mail, bypass the user-mode and supervisor-mode portions of 
the system logical name table. Therefore, Digital recommends that you define all 
logical names for important system components (public disks and directories, for 
example) in executive mode. (Only the operating system and privileged programs 
can create logical names in kernel mode.) 


13.3 Creating Logical Name Tables 

The system stores logical names and their equivalence strings in the following 
logical name tables: 


Process table 


J ob table 


Group table 


System table 


The names in this table are available only to your process and 
any subsequent subprocesses. Every process on the system has a 
process logical name table. When you log in, the system creates 
logical names for your process and places them in your process 
table. 

The name for your process table is LNM$PROCESS_TABLE. 
However, use the logical name LNM$PROCESS to refer to your 
process table. 

The names in this table are available to your process and to any 
of your subprocesses. All job tables are shareable so that all users 
can access them. 

The name for your job table is LNM$J OB_xxx (xxx represents the 
J ob I nformation Block address defined by the system for your job 
tree). However, use the logical name LNM$J OB to refer to your 
job table. 

The names in this table are available to all users in your 
group. The name for your group table is LNM$GROUP_xxx 
(xxx represents a group number.) However, use the logical name 
LNM$GROU P to refer to your group table. 

The names in this table are available to all users on the system. 
The name for your system table is LNM$SYSTEM_TABLE. 
However, use the logical name LNM$SYSTEM to refer to the 
system table. 


Some logical name tables are available only to your process; these tables are 
called process-private. Other tables are shareable; that is, they are available to 
other users on the system. 

In general, you create logical names in your process table. However, if you are a 
system manager or if your work requires you to add names to shareable tables 
(see Section 13.3.2), you must also work with the group and system tables. To 
create or delete a name in your group table, you need GRPNAM, GRPPRV, or 
SYSPRV privilege. To create or delete a name in the system table, you must have 
a UIC group number between 0 and 10 or SYSNAM or SYSPRV privilege. 

The CREATE/NAM E_TABLE command creates a logical name table and catalogs 
it in one of the di rectory logical name tables. Logical names that identify logical 
name tables or that translate iteratively to logical name tables must always be 
entered into one of the directory logical name tables. 

The following sections describe how to create process-private and shareable 
logical name tables. 
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13.3.1 Creating Process-Private Logical Name Tables 

To create a logical name table that is private to your process, create the table in 
LNM$PROCESS_DI RECTORY (the default). If the table needs to be shareable, 
specify /PARENT_TABLE=LNM$SYSTEM_DIRECTORY with the CREATE 
/NAME_TABLE command. 

The following example creates a process-private logical name table named TAX, 
places the definition for the logical name CREDIT in the table, and verifies the 
table's creation. The SHOW LOGICAL/TABLE command displays logical names 
in tables other than LNM$SYSTEM or LNM$PROCESS. 

S CREATE /NAME_TABLE TAX 

S DEFINE/TABLE=TAX CREDIT [ACCOUNT S . CURRENT ] CRED I T . DAT 
$ SHOW LOGICAL/TABLE=TAX CREDIT 

"CREDIT" = " [ACCOUNTS .CURRENT] CREDIT.DAT" (TAX) 

A name in a directory table can contain 1 to 31 characters. Only alphanumeric 
characters, the dollar sign ($), and the underscore (_) are valid. 

13.3.2 Creating Shareable Tables 

To create a shareable logical name table, use the /PARE NT_TABLE qualifier and 
specify the name of a shareable table. For example: 

$ CREATE /NAME_TABLE /P ARENT_TABLE=LNM$ S YSTEM_D IRECTORY NEWTAB 

The following privilege and access requirements apply to the use of shareable 
logical name tables: 

• To create a shareable logical name table, you must have SYSPRV privilege 
and EXECUTE (E ) access to the parent table. 

• To delete a shareable logical name table, you must have SYSPRV privilege or 
DELETE (D) access to the table. 

• To place a name in or delete a name from a shareable logical name table, you 
must have WRITE (W) access to the table. 

• To read (translate) a name in a shareable logical name table, you must have 
READ ( R ) access to the table. 

13.3.3 Adding a Logical Name to a Logical Name Table 

Generally, you do not need to change the default logical name table definitions set 
up in the directory tables LNM$PROCESS_DI RECTORY and LNM$SYSTEM_ 
DIRECTORY. Two reasons for changing the entries in the directory logical name 
tables are: 

1. To create another logical name table 

2. To change the order in which the system searches the logical name tables 

To place a logical name in a specific table, use the DEFI NE/TABLE command. 

For example: 

$ DEFINE/TABLE=NEWTAB TESTDIR [JONES . TESTFILES] 

The logical name TESTDIR is placed in NEWTAB (a user-defined logical name 
table). However, the next time you refer to TESTDIR in a file specification, the 
system looks for it in the process, job, group, and system logical name tables only. 
It does not look in the NEWTAB table. You need to include NEWTAB in the list 
of logical name tables that the system searches. The two ways to do this are as 
follows: 
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• Create a private definition of LNM$FILE_DEV within the process logical 
name directory table. 

• Redefine LNM$FILE_DEV within the system directory logical name table 
(requires SYSNAM or SYSPRV privilege). 

To add a logical name table to the process logical name directory table, redefine 
the logical name LNM$FILE_DEV within the process logical name directory 
table. For example, to add NEWTAB to the process logical name directory, enter 
the following command: 

$ DEFINE/TABLE=LNM$PROCESS_DIRECTORY LNM$FILE_DEV - 
_$ NEWTAB, LNM$PROCESS, LNM$J0B, LNM$ GROUP, LNM$ SYSTEM 

This example specifies that the system search the NEWTAB table first for the 
following reasons: 

• The process-private version of LNM$FILE_DEV is used before the default 
system version. 

• Within LNM$FILE_DEV, NEWTAB is listed before the process, job, group, 
and system logical name tables. 

Similarly, if you have SYSNAM or SYSPRV privileges, you can add a logical name 
table to the system directory logical name table. For example: 

$ DEFINE/TABLE=LNM$SYSTEM_DIRECTORY LNM$FILE_DEV - 
_$ NEWTAB, LNM$PROCESS, LNM$J0B, LNM$ GROUP, LNM$SYSTEM 

13.3.4 Defining the Protection for a Logical Name Table 

There are two ways to define the protection of a logical name table: 

• Use the /PROTECTION qualifier with the CREATE/NAM E_TABLE command. 
This command lets you set UlC-based protection for a shareable logical name 
table. 

• Apply ACL protection with the ACL editor or with the SET SECURITY /ACL 
/OBJ ECT_TYPE=LOGICAL_NAME_TABLE command. ACLs for system 
logical name tables are saved when the system reboots but ACLs for process 
logical name tables are not. You must reestablish ACLs on process logical 
name tables every time the system is booted. For more information, see the 
SET SECURITY /ACL command in the OpenVMS DCL Dictionary. 

13.3.5 Establishing Quotas for Logical Name Tables 

Quotas are used to limit the amount of system resources that a given logical 
name table can consume. The process, group, and system logical name tables 
have an infinite quota. By default, when you create a logical name table, it too 
has an unlimited quota. 

Using the /QUOTA Qualifier to Specify a Limit 

You can specify a quota to limit the size, in bytes, of a logical name table that you 
create. For example: 

$ CREATE /NAME_TABLE /QU0TA=5 0 0 ABC 

This creates the logical name table ABC and gives it a quota of 500 bytes. Before 
a logical name is created, the size of its data structure is checked against the 
quota remaining for the table. If there is insufficient quota available for the new 
entry, the system displays an error message. 
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Once you set the quota for a table, you cannot change it. If the table runs out of 
room, use the DEASSI GN command to delete old logical names. This frees space 
for your new logical names. 

Setting Job Table Quotas 

The job logical name table is a shareable table. The quota for a job logical name 
table is established when the table is created. The quota is determined by one or 
more of the following criteria: 

• TheJ TQUOTA value established for the user in the system user authorization 
file SYSUAF.DAT (if the first image activated by the process was the system 
image LOGINOUT). 

• The PQL$J TQUOTA quota list value specified in the call to the Create 
Process ($CREPRC) system service. 

• The/J OB_TABLE_QUOTA qualifier value on the RUN command used to 
create the detached process. 

• The SYSGEN parameter PQL_DJ TQUOTA (if none of the preceding 
conditions applies). The standard default value for this parameter is 
1024 bytes; however, the system manager can change it. The System 
Generation utility (SYSGEN) can be used to display and set the values of 
the parameters PQL_DJ TQUOTA (default job logical name table quota) and 
PQL_MJ TQUOTA (minimum job logical name table quota). 

A quota value of 0 for a job logical name table means there is no quota. For all 
practical purposes, the quota is unlimited. 

13.3.6 Using Logical Name Directory Tables 

When you enter a logical name as part of a command line, the system translates 
the logical name by searching the logical name tables in a certain order. The 
system stores information about existing logical name tables and the order in 
which they are searched in two logical name directory tables: 

• LNM$PROCESS_DI RECTORY, which is a process-private directory 

• LNM$SYSTEM_DI RECTORY, which is a shareable directory 

There is only one shareable directory for each system but each process has its own 
process-private directory. Both directories contain logical names that translate 
iteratively to table names. All logical name tables and any logical names that 
translate to tables are kept in these directories. 

13.3.7 Summary of Logical Name Tables and Logical Name Directory Tables 

Within each logical name table, the system defines some logical names for you. 
Table 13-1 describes each table and its system-defined logical names in the 
process directory table LNM$PROCESS_DIRECTORY. Table 13-2 describes 
each table and its system-defined logical names in the system directory table 
LNM$SYSTEM_DI RECTORY. 


13-11 


Logical Names: Defining Names for Devices and Files 
13.3 Creating Logical Name Tables 


Table 13-1 Process Directory Table LNM$PROCESS_DIRECTORY 
Logical Name Tables and Logical Names 


LNM$GROUP 


A logical name that is defined as LNM$GROUP_xxx, where xxx represents your group number. 
LNM$GROUP_xxx is the logical name table used by your UIC group. The table LNM$GROUP_xxx 
is cataloged in the system directory table. Therefore, LNM$GROUP is a logical name that translates 
iteratively to the name of your group logical name table. 

LNM$J OB 

A logical name that is defined as LN M$J OB_xxx, where xxx represents a number unique to your job tree. 
LNM$J OB_xxx is the logical name table used by your job. The table LNM$J OB_xxx is cataloged in the 
system directory table. Therefore, LNM$J OB is a logical name that translates iteratively to the name of 
your job logical name table. 

LNM$PROCESS 


A logical name that translates iteratively to LNM$PROCESS_TABLE, which is the name of your process 
logical name table. 


LNM$PROCESS_DI RECTORY 

The name of your process directory logical name table. 

LNM$PROCESS_TABLE (Process Table) 


The name of your process logical name table, which is available only to your process and any subsequent 
subprocesses. By default, the table contains the following logical names: 

SYS$COMMAND 1 The initial file (usually your terminal) from which DCL reads input. 

A file from which DCL reads input is called an input stream. The 
command interpreter uses SYS$COMMAND to "remember" the 
original input stream. 

SYS$DISK Default device established at login or changed by the SET DEFAULT 

command. 


SYS$ERROR 1 

SYS$INPUT 1 
SYS$N ET 


SYS$OUTPUT 1 

TT 


The default device or file to which DCL writes system error messages 
generated by warnings, errors, and severe errors. 

The default file from which DCL reads input. 

The source process that invokes a target process in DECnet for 
OpenVMS task-to-task communication. When opened by the target 
process, SYS$NET represents the logical link over which that process 
can exchange data with its partner. SYS$NET is defined only during 
task-to-task communication. 

The default file (usually your terminal) to which DCL writes output. A 
file to which DCL writes output is called an output stream. 

Default device name for terminals. 


J ob Table, LNM$J OB xxx 

Contains logical names that are available to all processes in your job tree. There is one job table for each 
job tree in the system. 

The system places logical names created for mounted disks, mounted tapes, and temporary mailboxes in the 
job logical name table. In addition, the system creates the following logical names: 

SYS$LOGIN Your default device and directory when you log in. 

SYS$LOGI N_DEVI CE Your default device when you log in. 


x The logical names SYS$INPUT, SYS$OUTPUT, SYS$ERROR, and SYS$COMMAND refer to process-permanent files, 
files that remain open for the life of the process. For more information on process-permanent files, see Section 13.7. 


(continued on next page) 
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Table 13-1 (Cont.) Process Directory Table LNM$PROCESS_DIRECTORY 


Logical Name Tables and Logical Names 


SYS$RE M_l D 


SYS$REM_NODE 

SYS$SCRATCH 


For jobs initiated through a DECnet for OpenVMS network connection, 
the identification of the process on the remote node from which the 
job was originated. On an OpenVMS operating system, if proxy logins 
are enabled, this identification is the process's user name; or if proxy 
logins are not enabled, this is the process identification (PI D) number. 
(Proxy logins to proxy accounts allow users to access files across the 
network without specifying an access control string.) 

For jobs initiated through a DECnet for OpenVMS network connection, 
the name of the remote node from which the job was originated. 

Default device and directory to which temporary files are written. 


Table 13-2 System Directory Table LNM$SYSTEM_DIRECTORY 
Logical Name Tables and Logical Names 


LNM$DCL_LOGICAL 

A logical name defined as LNM$FI LE_DEV. Translates iteratively into the list of logical name tables 
searched and displayed by the SHOW LOGICAL command, the SHOW TRANSLATION command, and the 
F$TRNLNM lexical function. By default, these commands search and display the process, job, group, and 
system logical name tables, in that order. 

LNM$DI RECTORIES 

A logical name defined as LNM$PROCESS_DI RECTORY and LN M$SYSTEM_DI RECTORY. 

LNM$FILE_DEV 

A logical name defined as the list of logical name tables searched by the system when processing a file 
specification. Defined as LNM$PROCESS, LN M$J OB, LN M$GROU P, and LNM$SYSTEM so the system 
searches the process, job, group, and system logical name tables, in that order. 

LNM$GROUP_xxx (Group Table) 

Contains logical names that are available to all users with the same user identification code(UIC) group 
number. The group table is named LNM$GROUP_xxx, where xxx represents your UIC group number. Use 
the logical name LNM$GROU P to refer to your group table. Every group on the system has a corresponding 
group logical name table. 

LNM$J OB xxx 

A job logical name table, where xxx is a number unique to this job tree. There is an LNM$J OB_xxx logical 
name table for each job in the system. 

LNM$PERMANENT MAILBOX 

A logical name that is defined as LNM$SYSTEM. Logical names associated with permanent mailboxes are 
entered in the logical name table to which the logical name LNM$PERMANENT_MAILBOX iteratively 
translates. 

LNM$SYSTEM 

A logical name that translates iteratively to LNM$SYSTEM_TABLE. 

LNM$SYSTEM TABLE (System Table) 

The name of the system logical name table. The system table contains logical names that are available to 
all users of the system at the system level. Use the logical name LNM$SY STEM to refer to it. 

The following logical names are automatically defined in the system table when the system starts up: 

DBG$INPUT Default input stream for the OpenVMS Debugger, equated to 

SYS$I NPUT at the process level. 

(continued on next page) 
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Logical Name Tables and Logical Names 


DBG$OUTPUT 

Default output stream for the OpenVMS Debugger, equated to 

SYS$COM MON 

SYS$OUTPUT at the process level. 

SYS$SYSDEVI CE :[SYSn.SYSCOM MON .], where n is the root 
directory number of your processor. Device and directory name for 
the common part of SYS$SY SROOT. 

SYS$ERRORLOG 

Device and directory name of error log data files. By default, 

SY S$SY SROOT :[SY SE RR], 

SYS$EXAMPLES 

Device and directory name of system examples. By default, 

SYS$SY SROOT :[SYSH LP.EXAM PLES], 

SYS$HELP 

Device and directory name of system help files. By default, 

SY S$SY SROOT:[SY SH L P ]. 

SYS$I NSTRUCTION 

Device and directory name of system instruction data files. By default, 
SY S$SY SROOT:[SY SC B 1 ]. 

SYS$LI BRARY 

Device and directory name of system libraries. By default, 

SY S$SY SROOT :[SY SL 1 B ]. 

SYS$LOADABLE_l MAGES 

Device and directory of operating system executive loadable images, 
device drivers, and other executive-loaded code. By default, 
SYS$SYSROOT:[SYS$LDR], 

SYS$MAI NTENANCE 

Device and directory name of system maintenance files. By default, 

SY S$SY SROOT :[SY SM Al NT], 

SYS$MANAGER 

Device and directory name of system manager files. By default, 

SY S$SY SROOT :[SY SM GR], 

SYS$MESSAGE 

Device and directory name of system message files. By default, 

SY S$SY SROOT :[SY SM SG], 

SYS$NODE 

Network node name for the local system if DECnet for OpenVMS is 
active on the system and you are connected to a network. 

SYS$PROCDMP 

Directory (set by user) into which image dumps are to be written. No 
default setting. 

SYS$SHARE 

Device and directory name of system shareable images. By default, 

SY S$SY SROOT :[SY SL 1 B ]. 

SYS$SPECI FIC 

Device and directory name for node-specific part of SYS$SYSDEVICE. 
By default, SYS$SYSDEVICE:[SYSn.], where n is the root directory 
number of your processor. 

SYS$STARTUP 

Device and directory name of system startup files. By default, a search 
list that points first to SYS$SYSROOT:[SYS$STARTUP] and then to 
SYS$MANAGER. 

SYS$SYSDEVICE 

SYS$SYSROOT 

System disk containing system directories (usually SYS$DISK). 

Device and root directory for system directories. By default, a 
search list that points first to SYS$SYSDEVICE:[SYSn.], where n 
is the root directory number of your processor, and then points to 
SYS$COMMON. 

SYS$SYSTEM 

Device and directory of operating system programs and procedures. 

By default, SYS$SYSROOT:[SYSEXE], 

SYS$TEST 

Device and directory name of User Environment Test Package (UETP) 
files. By default, SYS$SYSROOT:[SYSTEST], 

(continued on next page) 
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Table 13-2 (Cont.) System Directory Table LNM$SYSTEM_DIRECTORY 
Logical Name Tables and Logical Names 


SYS$UPDATE Device and directory name of system update files. By default, 

SYS$SYSROOT:[SYSUPD], 

LNM$TE MPORARYMAI L BOX 

A logical name that is defined as LNM$J OB. (Logical names associated with temporary mailboxes are 
entered in the logical name table to which the logical name LNM$TEMPORARY_MAILBOX iteratively 
translates.) 


13.4 Displaying Logical Names 

Use the SHOW LOGICAL command to display logical names and their 
equivalence strings. For example, to display the equivalence string for the 
logical name WORKFI LE, enter the following command: 

S SHOW LOGICAL WORKFILE 

"WORKFILE" = "DISK2: [WALSH.REPORTSJWORK_SUMMARY.DAT" (LNM$PROCESS_TABLE) 

This command displays the logical name, its translation, and the table where the 
logical name is found. 

Sometimes the definition of a logical name includes another logical name. The 
SHOW LOGICAL command performs iterative translations. It then displays both 
the equivalence string and the level of translation. For example, to display the 
logical nameMYDISK, enter the following command: 

$ SHOW LOGICAL MYDISK 

"MYDISK" = "WORM" (LNM$PROCESS_TABLE) 

1 "WORM" = "$255$DUA17 : " (LNM$SYSTEM_TABLE) 

Level numbers are zero based; that is, 0 is the first level, 1 is the second, and so 
on. I n this example, two translations are performed. The number 1 indicates the 
second level of translation. 

To display only the first translation found for a specified logical name, use the 
SHOW TRANSLATION command. (For more information, see the Open VMS 
DCL Dictionary.) 

13.4.1 Displaying Process-Permanent Files 

If you use the SHOW LOGICAL command to determine the equivalence string for 
a process-permanent file (see Section 13.7), the command displays only the device 
portion of the string. For example: 

$ SHOW LOGICAL SYS$INPUT 

"SYS$INPUT" = "_TTB4 : " (LNM$PROCESS_TABLE) 

Displaying the Access Mode for a Logical Name 

To display the access mode for a logical name, use the SHOW LOGICAL/FULL 
command, as follows: 

$ SHOW LOGICAL/FULL PROJECT 

"PROJECT" [super] = "DISKI : [JONES] " (LNM$PROCESS_TABLE) 

This example displays the logical name PROJ ECT in supervisor mode. 
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13.4.2 Displaying a Logical Name Table 

By default, the SHOW LOGICAL command searches your process, job, group, and 
system tables. However, you can change the default search order or specify other 
logical name tables to be searched. To display the entries in a particular logical 
name table, use the /TABLE qualifier. For example: 

$ SHOW LOGICAL/TABLE=LNM$PROCESS 
(LNM$PROCESS_TABLE) 

"DECW$DISPLAY" = "_WSA30:" 

" SYS $ COMMAND" = "_FIFI$VTA65 : " 

"SYS$DISK" [super] = "W0RK1:" 

"SYS$DISK" [exec] = "W0RK1:" 

"SYS$ERR0R" = "_FIFI$VTA65 : " 

" SYS $ INPUT" = "_FIFI$VTA65 : " 

"SYS$OUTPUT" [super] = "_FIFI$VTA65 : " 

"SYS$OUTPUT" [exec] = "_FIFI$VTA65 : " 

"TT" = "_VTA65 : " 

This command displays the logical names in the process logical name table 
(LN M $PROCESS). You can also use the /GROUP, /SYSTEM, /) OB, and 
/PROCESS qualifiers to display the logical names in the group, system, job, 
and process logical name tables, respectively. 

13.4.3 Displaying Directory Table Structure 

To display the relationship of directory tables to logical name tables, enter the 
SHOW LOGICAL/STRUCTURE command, as shown in the following example: 

$ SHOW LOGICAL/STRUCTURE 
(LNM$PROCESS_DIRECTORY) 

(LNM$PROCESS_TABLE) 

(LNM$SYSTEM_DIRECTORY) 

( LNM$ GROUP_000360) 

(LNM$JOB_806E98E0) 

( LNM$ S YSTEM_TABLE ) 

This example shows the process table, LNM$PROCESS_TABLE, in the process 
directory table, and the group, job, and system tables in the system directory 
table. 

13.5 Deleting Logical Names and Logical Name Tables 

To delete a logical name, use the DEASSIGN command. For example, the 
following command line deletes the logical name WORKFI LE: 

$ DEASSIGN WORKFILE 

When you define logical names in your process and job logical name tables, they 
are not deleted until your process terminates or they are explicitly deleted by 
user actions. However, if you specify the /USE R_M ODE qualifier to the DEFI NE 
command, the logical name is defined in the process logical name table and 
deleted automatically after executing the next command image. 

To delete a logical name ending with a colon, specify two colons. The DEASSIGN 
command, like the ASSIGN command, removes one colon before it searches the 
logical name table for a match. 

To delete a logical name table, specify the table that contains it (the system or 
process directory logical name table) and the name of the table. All logical names 
in descendant tables (and the descendant tables themselves) are deleted when 
you delete a parent logical name table. For example, to delete the logical name 
table TAX from the process directory table, specify the following command line: 
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$ DEASSIGN/TABLE=LNM$PROCESS_DIRECTORY TAX 

To delete a shareable logical name table, you must have DELETE access to the 
table or SYSPRV privilege. 

13.6 Using Logical Names for File Input/Output (I/O) 

In command procedures, you can use logical names to perform input and output 
from files. When you open a file with the OPEN command, you also create a 
logical name for the file. The READ, WRITE, and CLOSE commands use the 
logical name and not the actual file specification to refer to the file. For example: 

$ OPEN INFILE DISK3: [WALSH] DATA.DAT 
$ READ INFILE RECORD 
$ CLOSE INFILE 

When theCLOSE command closes the file, it deassigns the logical nameINFILE. 

For more information on using logical names in command procedures, see 
Chapter 15. 

13.7 Redefining Process-Permanent Logical Names 

Process- permanent logical names are created by DCL when you log in and they 
remain defined for the life of your process. You cannot deassign these logical 
names. You can redefine them (by specifying a different equivalence string in a 
DEFI NE command) but if the redefined name is later deassigned, the process- 
permanent name is reestablished. The following process-permanent logical names 
are available: 

• SY S$l N PUT 

Logical name that refers to the default input device or file 

• SY S$OUTPUT 

Logical name that refers to the default output device or file 

• SYS$ERROR 

Logical name that refers to the default device or file to which the system 
writes messages 

• SYS$COMMAND 

Logical name that refers to the value of SYS$I N PUT when you login 

When you use the system interactively, DCL equates SYS$INPUT, SYS$OUTPUT, 
SYS$ERROR, and SYS$COMMAND to your terminal. However, when 
you execute command procedures and submit batch jobs, DCL creates new 
equivalence strings for these logical names. 

When you execute a command procedure interactively, the following occur: 

• SYS$INPUT is equated to the command procedure. Therefore, DCL obtains 
data from the command procedure. This assignment is temporary. After the 
command procedure terminates, SYS$INPUT regains its original value. 

• SY S$OUTPUT, SYS$COMMAND, and SYS$ERROR remain equated to the 
terminal. 

When you submit a batch job, the following occur: 

• SYS$INPUT and SYS$COMM AND are equated to the batch job command 
procedure. 
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• SYS$OUTPUT and SYS$ERROR are equated to the batch job log file. 

When you nest command procedures (that is, when you write a command 
procedure that executes other command procedures), the equivalence string 
for SYS$INPUT changes to point to the command procedure that is currently 
executing. However, the equivalence strings for SYS$OUTPUT, SYS$ERROR, 
and SYS$COM MAND remain the same unless you explicitly change them. 

In addition, when you enter a command that opens a file, DCL opens the file as a 
process-permanent file. For example, if you open a file with the OPEN command, 
this file is opened as a process-permanent file. The file remains open until you 
explicitly close the file or until you logout. 

Process-permanent files are stored in a special area in memory. Note that if you 
keep a large number of files open at the same time, you can exhaust this area. If 
this occurs, close some of the files (or log out). 

The following sections describe how to use process-permanent logical names as 
file specifications. I n command procedures, you can use these names to read data 
from the terminal and to display data (see Chapter 15). 

13.7.1 Redefining SYS$INPUT 

You can redefine SYS$I NPUT so that a command procedure reads input from the 
terminal or another file. For example, to edit a file from a command procedure, 
include the following lines in the command procedure: 

$ DEFINE/USER_MODE SYS$INPUT SYS$COMMAND 
$ EDIT/TPU MYFILE.DAT 


In the previous example, SYS$INPUT is redefined as SYS$COMMAND so 
that the editor obtains input from the terminal rather than from the command 
procedure file (the default). SYS$COMMAND refers to the terminal, the initial 
input stream when you logged in. The /USER_MODE qualifier tells the command 
procedure that SYS$I NPUT is redefined only for the duration of the next image. 
In this example, the next image is the editor. When the editor is finished, 
SYS$INPUT resumes its default value. In this case, the default value is the 
command procedure file. 

Note that if you redefine SYS$I NPUT, DCL ignores your definition. DCL always 
obtains input from the default input stream. However, images such as command 
procedures can use your definition for SYS$INPUT. 

13.7.2 Redefining SYS$OUTPUT 

You can redefine SYS$OUTPUT to redirect output from your default device 
to another file. When you redefine SYS$OUTPUT, the system opens a file 
with the name you specify in the logical name assignment. When you define 
SYS$OUTPUT, all subsequent output is directed to the new file. 

In the following example, SYS$OUTPUT is defined as MYFILE.LIS before 
the SHOW DEVICES command is entered. The display produced by SHOW 
DEVICES is directed to MYFILE.LIS in your current directory rather than to 
your terminal. You can manipulate this data as you would any other text file. 

$ DEFINE SYS$OUTPUT MYFILE.LIS 
$ SHOW DEVICES 
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Remember to deassign SYS$OUTPUT or output will continue to be written to 
the file you specify. Note that you can redefine SYS$OUTPUT in user mode 
(with DEFI NE/USER_MODE) to redirect output from an image. This definition 
is in effect only until the next command image is executed. Once the command 
image is executed (that is, the output is captured in a file), the logical name 
SYS$OUTPUT resumes its default value. 

When you log in, the system creates two logical names called SYS$OUTPUT. One 
name is created in executive mode; the other name is created in supervisor mode. 
You can supersede the supervisor mode logical name by redefining SYS$OUTPUT. 
If you deassign the supervisor mode name, the system redefines SYS$OUTPUT 
in supervisor mode, using the executive mode equivalence string. You cannot 
deassign the executive mode name. 

I n the following example, SYS$OUTPUT is redefined tothefileTEMP.DAT. 
When SYS$OUTPUT is redefined, output from DCL and from images is directed 
to the file TEMP.DAT. The output from the SHOW LOGICAL command and 
from the SHOW TIME command is also sent toTEMP.DAT. When you deassign 
SYS$OUTPUT, the system closesthefileTEMP.DAT and redefines SYS$OUTPUT 
to your terminal. When you enter the TYPE command, the output collected in 
TEMP.DAT displays on your terminal. 

$ DEFINE SYS$OUTPUT TEMP.DAT 
$ SHOW LOGICAL SYS$OUTPUT 
$ SHOW TIME 
$ DEASSIGN SYS$OUTPUT 
$ TYPE TEMP.DAT 

"SYS$OUTPUT" = "DISKI : " (LNM$PROCESS_TABLE) 

06-MAY-1994 13:26:53 

When you redefine SYS$OUTPUT to a file, the logical name contains only the 
device portion of the file specification even though the output is directed to the 
file you specify. I n the previous example, when SYS$OUTPUT was redefined, the 
equivalence string contained the device name Dl SKI, not the full file specification. 

If the system cannot open the file you specify when you redefine SYS$OUTPUT, 
an error message displays. 

After you redefine SYS$OUTPUT, most commands direct output to the existing 
version of the file. However, certain commands create a new version of the file 
before they write output. 

13.7.3 Redefining SYS$ERROR 

You can redefine SYS$ERROR to direct error messages to a specified file. 
However, if you redefine SYS$ERROR so it is different from SYS$OUTPUT 
(or if you redefine SYS$OUTPUT without also redefining SYS$ERROR), DCL 
commands send informational, warning, error, and severe error messages to 
both SYS$ERROR and SYS$OUTPUT. Therefore, you receive these messages 
twice— once in the file indicated by the definition of SYS$ERROR and once in 
the file indicated by SYS$OUTPUT. Success messages are sent only to the file 
indicated by SYS$OUTPUT. 

DCL commands and images, which use standard error display mechanisms, send 
error messages to both SYS$ERROR and SYS$OUTPUT even when SYS$ERROR 
is different from SYS$OUTPUT. However, if you redefine SYS$ERROR, then run 
an image that references SYS$ERROR, the image sends error messages only to 
the file indicated by SYS$ERROR. This is true even if SYS$ERROR is different 
from SYS$OUTPUT. 
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13.7.4 Redefining SYS$COMMAND 

Although you can redefine SYS$COMMAND, DCL ignores your definition. DCL 
always uses the default definition for your initial input stream. However, if you 
execute an image that references SYS$COMMAND, the image can use your new 
definition. 

13.8 Understanding Logical Name Translation 

When the system reads a file specification or device name in a DCL command 
line, it examines the file specification or device name to see whether the leftmost 
component is a logical name. If the leftmost component ends with a colon, space, 
comma, or a line terminator (for example, Return), the system attempts to 
translate it as a logical name. If the leftmost component ends with any other 
character, the system does not attempt to translate it as a logical name. 

After you enter the command shown in the following example, the system checks 
to see whether PUP is a logical name because PUP is the leftmost component of 
the file specification. Because the leftmost component is terminated with Return, 
the system attempts to translate PUP. 

$ TYPE PUP [Return] 

After you enter the command shown in the next example, the system checks 
whether DISK is a logical name. The system attempts to translate Dl SK because 
it is the leftmost component and ends with a colon. The system does not check 
PUP. 

$ TYPE DISK:PUP [RiTEE] 

In the third example, the system does not try to translate [DRYSDALE]PUP 
because the leftmost component ends with a right square bracket ( ] ): 

$ TYPE [DRYSDALE] PUP [Rejum] 

13.8.1 Modifying Logical Name Translation 

By default, when the system translates logical names in file specifications, it 
searches the process, job, group, and system tables in that order and uses the 
first match it finds. 

There are two ways to change the default search order: 

• Redefine the logical name LNM$FI LE_DEV within the system directory table. 

• Create a private definition of LNM$FILE_DEV within the process directory 
table. For example, if you want the system to search the process and system 
tables only, enter the following command: 

$ DEFINE/TABLE=LNM$PROCESS_DIRECTORY - 
_$ LNMSFILE_DEV LNM$PROCESS, LNM$SYSTEM 

I n this example, the equivalence strings for LNM$FI LE_DEV do not include 
LNM$J OB and LNM$GROUP. Therefore, subsequent commands that need to 
translate a logical name will not search the job or group tables. 
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13.8.2 Iterative Translation 

Logical name translation can be iterative: after the system translates a logical 
name, it repeats the translation process for any logical names it finds contained 
within the first logical name. For example: 

$ DEFINE DISK DUA1 : 

$ DEFINE MEMO DISK : [JEFF .MEMOS] COMPLAINT . TXT 

In this example, the first DEFINE command equates the logical name Dl SK 
to the device name DUA1. The second DEFINE command equates the logical 
name MEMO to the file specification DISK:[J EFF.MEMOSjCOMPLAINT.TXT. 
When the system translates the logical name MEMO, it finds the equivalence 
string Dl SK :|J EFF.M EMOS]COM PLAI NT.TXT. It then checks to see whether the 
leftmost component in this file specification ends in a colon, a space, a comma, or 
an end-of-line terminator. It finds a colon after Dl SK. The system translates that 
logical name also. The final translation of the file specification is as follows: 

DUAl : [ JEFF . MEMOS ] COMPLAINT . TXT 

The system limits the number of levels to which it performs logical name 
translation. The number of levels varies among system facilities but it is at least 
nine. If you define more than the system-determined number of levels or if you 
create a circular definition, an error occurs when the logical name is used. 

13.8.3 System Defaults During Logical Name Translation 

When the system translates a logical name, it fills in any missing fields in a 
file specification. It fills them in with the current default device, directory, and 
version number. When you use a logical name to specify the input file for a 
command, the command uses the logical name to assign a file specification to the 
output file as well. 

If the equivalence string contains a file name and file type, the output file is 
given the same file name and file type. If the equivalence string does not contain 
a file type, a default file type is supplied. The file type supplied depends on the 
command you are using. 

When you use logical names in a list of input files, the equivalence string of each 
logical name provides a temporary default. For example: 

$ SET DEFAULT DBA2: [CASEY] 

$ DEFINE MAL DBA1 : [MALCOLM] 

$ DEFINE HIG [HIGGINS] 

$ PRINT ALPHA, MAL: BETA, HIG: GAMMA 

The PRI NT command looks for the following files: 

DBA2:[CASEY]ALPHA.LIS 

DBAl:[MALCOLM]BETA.LIS 

DBA1:[HIGGINS]GAMMA.LIS 

Because a device name was not specified for the logical name FI I G, the device 
name for MAL defines DBA1 as the temporary default device. 
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13.8.4 Translating a Search List in a File Specification 

When you use a search list in a file specification, the search list is translated as 
follows: 

• If the search list contains only a device, the original default directory is 
searched. 

• If the search list contains a device and a directory, both are used to construct 
a complete file specification. 

For example: 

$ DEFINE FIFI DISKI : [FRED] , DISK2 : [GLADYS] , DISK3 : [MEATBALL . SUB] 

$ DIRECTORY FIFI :MEM0 . LIS 

This command displays the following files: 

DISKl:[FRED]MEMO.LIS 

DISK2:[GLADYS]MEMO.LIS 

Dl SK3:[MEATBALL.SUB]M EMO.LI S 

When you specify a search list as the first part of the parameter for the SET 
DEFAULT command, the system assigns the search list name, untranslated, to 
SYS$DISK. (SYS$DISK is a logical name that translates to your default disk.) 
For example: 

$ SHOW DEFAULT 

DISK2 : [MEATBALL. SUB] 

$ DEFINE FIFI DISKI : [FRED] , DISK2 : [GLADYS] , DISK3 : 

$ SET DEFAULT FIFI 
$ SHOW DEFAULT 

FIFI: [MEATBALL. SUB] 

DISKI : [FRED] 

DISK2: [GLADYS] 

DISK3: [MEATBALL. SUB] 

At the beginning of this example, the default disk and directory are 
Dl SK2:[M EATBALL.SU B], Next, a search list is defined. The SET DEFAULT 
command uses the search list as its parameter. When you enter the SHOW 
DEFAULT command a second time, the default directory has not changed. 
However, the search list FI FI is displayed as the default device along with its 
equivalence strings. The SHOW DEFAULT command displays the search list in 
the order in which the search list is evaluated by the system. 

Note 

When you specify a search list as the first part of a parameter for the 
SET DEFAULT command, each equivalence string in the search list must 
contain a device name. 


When you use a search list with a command that does not accept wildcards in a 
file specification, the system forms a file specification by using each equivalence 
string in the search list until a file specification for an existing file is found. The 
command affects only the first file found. For example: 

$ DEFINE DECEMBER DISKI : [FRED] ,W0RK2 : [BARNEY] 

$ EDIT/EDT DECEMBER: QUOTAS. TXT 


13-22 


Logical Names: Defining Names for Devices and Files 
13.8 Understanding Logical Name Translation 

First, the system forms the file specification DISKl:[FRED]QUOTAS.TXT and 
searches for that file. lfQUOTAS.TXT is found in DISK1:[FRED], it is opened 
for editing. No other files are subsequently opened. If QUOTAS.TXT is not 
found in DISK1:[FRED], the system searches for it in WORK2:[BARNEY], 

If QUOTAS.TXT is found there, it is opened. If it is not found, an error 
message displays. The system displays an error message only after it checks 
all equivalence strings in a search list. Then, the system reports an error only on 
the last file it attempts to find. 

The RUN command is an exception. When the RUN command is followed by a 
search list, the system forms file specifications as described previously. Flowever, 
the system then checks to see whether any of the files in the list are installed 
images. The system runs the first file in the search list that is an installed image. 
Then, the RUN command terminates. 

If none of the file specifications are installed images, the system repeats the 
process of forming file specifications. This time it looks for each file specification 
on the disk. It runs the first file it finds there. An error message is displayed if 
none of the specified files is found in either the known file list or on the disk. 

13.8.5 Determining the Search Order for Multiple Search Lists 

A file specification can contain more than one search list. When this occurs, 
each item in the file name search list is used, while the first device name is held 
constant. After all the items in the file name search list have been combined 
with the first device name, they are combined with the second device name. This 
continues until each device has been searched. 

The following example shows a file specification that has a search list in the file 
name and in the device name: 

$ DEFINE FILE CHAP1.RN0, CHAP2.RN0 
$ DEFINE DISK W0RK1 : [ROSE] , W0RK2 : [THORN] 

$ SET DEFAULT DISK 
$ DIRECTORY FILE 

Directory W0RK1:[R0SE] 

CHAP1 . RNO; 2 CHAP 2 ,RN0; 1 

Total of 2 files. 

Directory W0RK2 : [THORN] 

CHAP 1. RNO; 1 CHAP2 .RNO; 1 

Total of 2 files. 

Grand total of 2 directories, 4 files. 

The directory listing for each file name is given, first for WORKl:[ROSE] and 
second for WORK2:[THORN], 

You can also have iterative (nested) search lists when one name in a search list 
translates to another search list. If this occurs, the system uses each name in a 
sublist before continuing to the next upper level name. For example: 

$ DEFINE NESTED FRED.DAT, NEW_LIST, RICKY.DAT 
$ DEFINE NEW_LIST ETHEL.DAT, LUCY . DAT 

The search order for the search list NESTED is as follows: 

FRED.DAT 

ETHEL.DAT 

LUCY.DAT 
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RICKY.DAT 

13.8.6 Processing Logical Names in Multiple Tables 

Multiple tables with the same name can exist. For example, there can be both 
a process-private and a shareable table called MY_TABLE. The process-private 
version always takes precedence over the shareable table in all logical name 
table processing. When a logical name such as LNM$FILE_DEV is used as a 
table name, the logical name is iteratively translated until a list of table names 
is formed. During this iterative translation, each name is first translated in the 
process directory. If this translation fails, it is then translated in the system 
directory. This order of precedence cannot be changed. As a consequence of this 
ordering, a logical name placed in the process directory table for use as a table 
name always takes precedence over any identical name residing in the system 
di rectory. 
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Symbols: Defining Commands and 

Expressions 


A symbol is a name that represents a numeric, character, or logical value (such 
as true or false). When you use a symbol in a DCL command line, DCL replaces 
the symbol with its value before executing the command. 

You can use symbols in the following ways: 

• As synonyms for commands, parameters, or command lines. I nstead of typing 
a long command line, you can create a symbol to use instead. For example, 
you can create a symbol to set default to a directory that you access often. 
The following commands show how to define and use the symbol WORK to 
set default to the WORKl:[| ONES.WORK] directory: 

$ WORK :== SET DEFAULT DISKI : [JONES .WORK] 

$ WORK 

$ SHOW DEFAULT 

DISKI : [JONES. WORK] 

• To define a foreign command, which allows you to execute an image by 
entering only the symbol name. The command is "foreign" because it is 
unknown to DCL. 

• I n command procedure files, to perform programming tasks such as 
conditional execution and substitution of variables. 

You can use symbols as variables in expressions or to pass parameters to 
and from command procedures. In addition, DCL commands such as READ, 
WRITE, and I NQUI RE use symbols to refer to data records. 

This chapter describes how to create and use symbols to represent commands, 
character strings, and numeric data. It also describes how you can combine 
symbols into expressions to manipulate the values that the symbols represent. 

14.1 When to Use a Logical Name or Symbol 

Although logical names and symbols appear similar, they are utilized differently. 
Table 14-1 compares the function, usage, and other characteristics of logical 
names and symbols. 
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Table 14-1 Comparison of Logical Names and Symbols 


Characteristic Logical Names Symbols 


Function 

Represent device, directory, file, 
queue, and other system object 
specifications. 

Represent commands or portions of 
command strings. 

Usage 

Are used in place of any 
complete device, directory, 
file, queue or other system 
object specification. Logical 
names must be used as part of 
a command string parameter to 
be passed to the file system for 
translation. 

Are used in place of any command 
string. Symbols must be used as the 
first word in a command string to be 
translated by the command language 
i nterpreter. 

Storage 

Are stored in your process, job, 
group, or system logical name 
table. See Section 13.3. 

Are stored in your global or local 
symbol table. See Section 14.7. 

Creation 

Use either the ASSIGN or 
DEFINE command to create 
a logical name. See Section 13.2. 

Use an assignment statement 
( = or ==) to create a symbol. See 
Section 14.2. 

Display 

Use either the SHOW LOGICAL 
or SHOW TRANSLATION 
command to display a logical 
name. See Section 13.4. 

Use the SHOW SYMBOL command to 
display a symbol. See Section 14.3. 

Deletion 

Use the DEASSIGN command 
to delete a logical name. See 
Section 13.5. 

Use the DELETE/SYMBOL command 
to delete a symbol. See Section 14.4. 


14.2 Creating Symbols 

You can create two types of symbols, local and global. Local symbols are 
accessible from the current command level and from command procedures 
executed from the current command level. Global symbols are accessible at all 
command levels. 

You can define a symbol with a character string, a number, a lexical function, a 
logical value, or another symbol. The symbol name can be 1 to 255 characters 
long and must begin with a letter, an underscore (_), or a dollar sign ($). In a 
symbol name, both lowercase and uppercase letters are treated as uppercase. 

To create a symbol, use the assignment statement ( = or ==) or the string 
assignment (:=or :==). When you use the string assignment, all alphabetic 
characters are converted to uppercase and multiple spaces and tabs are 
compressed to a single space. You can use string assignments to create a 
symbol that represents a DCL command or to define a foreign command. To 
continue a character string over two lines in a string assignment, use a single 
hyphen. 
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The following table shows examples of assignment statements and string 
assignments: 


Task 

Example 

Creating a Local Symbol 

symbol-name = value 

$ SS = "SHOW SYMBOL" 


Creates the local symbol SS and assigns it to the DCL command 
SHOW SYMBOL. 

symbol-name := 

$ DB := DIRECTORY ACCOUNTS : [BOLIVAR] 

value 

Creates the local symbol DB and assigns it to the DCL command 
DIRECTORY ACCOU NTS:[BOLI VAR], 

Creating a Global Symbol 

symbol-name = = 

$ DC == " DIRECTORY /SI ZE=ALL DISKI : [JONES . TAX] MONEY . LIS" 

value 

Creates the global symbol DC to represent a DCL command line. 
The DCL command DIRECTORY is executed with the specified 
qualifiers when you enter the symbol name. 

symbol-name := = 
value 

$ READY :== PRINT/CONFIRM/QUEUE=AKI$LN03/NOTIFY/RESTART 
$ READY FILE .DAT 


Creates the global symbol READY to represent a DCL command 
line. The DCL command PRINT is executed with the specified 
qualifiers when you enter the symbol name. 


You can also create symbols by using the READ and I NQUI RE commands (see 
Chapter 15). 

14.2.1 Using Symbols to Represent DCL Commands 

You can define a symbol to represent a DCL command in your login command file 
(LOGIN.COM) or interactively at DCL level. When you define the symbol in your 
login command file, you can use the symbol each time you log in; when you define 
the symbol interactively, the symbol can be used only during the current process. 

If you define a symbol with the same name as a DCL command, your definition 
overrides the DCL command name. For example, if you define the symbol HELP 
as the command TYPE HELP.LST, you can no longer invoke the system's Help 
uti I ity by typi ng H E L P. 

14.2.2 Abbreviating Symbols 

Use the asterisk (* ) to create a symbol that can be abbreviated. The following 
example creates the local symbol PRI NT, which can be abbreviated as PR, PR I, or 
PRIN: 

$ PR*INT = "PRINT/CONFIRM/QUEUE=AKI$LN03/NOTIFY/RESTART " 

To execute the DCL command PRI NT with the specified qualifiers, you can enter 
the symbol or any of its abbreviations. 
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Generally, you can use abbreviated symbol definitions in any situation that 
allows a symbol to be used. Symbols that involve substring replacement are an 
exception. See Section 14.6.1.3 for more information. 

Note that existing symbols might be superseded. If an existing symbol exactly 
matches the new symbol at or past the asterisk, the new symbol replaces the 
existing symbol. In addition, you cannot define another symbol whose name 
partly matches the existing symbol at or past the asterisk. 

14.2.3 Defining Foreign Commands 

If you equate the file specification of a non-DCL image to a symbol, you can run 
the image by typing the symbol name. A symbol that runs an image is referred 
to as a foreign command. A foreign command is an image that is not recognized 
by the command interpreter as a DCL command. 

The formats for defining a symbol as a foreign command are as follows: 

symbol-name :=[=] $image-file-spec 
symbol-name =[=] "$image-file-spec" 

For example, to define the global symbol PRI NTALL to execute the image 
DISKl:[ACCOUNTS]PRINTALL.EXE, enter the following command: 

$ PRINTALL :== $ [ACCOUNTS] PRINTALL 

Note that when the dollar sign ($) precedes a file specification at the beginning 
of a symbol definition, without any space between the dollar sign and the file 
specification, the request to run the image is implied. 

In a command line, PRINTALL could be followed by a parameter. In the following 
example, the file specification RAT.DAT is a parameter that is passed to the 
image defined by PRI NTALL: 

$ PRINTALL RAT.DAT 

For the image file specification, the default device and directory name is 
SYS$SYSTEM , the default file type is .EXE, and the default file version number 
is the highest version. 

The command interpreter looks for symbols enclosed by apostrophes (') and 
translates them. Thus, if you use symbols or lexical functions preceded by 
apostrophes to specify parameters, symbol substitution occurs (see Section 14.9). 
Otherwise, the command interpreter does not parse the line. The image must 
obtain the parameter and perform any parsing or evaluation of the command 
line. 

An alternative to using a foreign command is to define new commands with the 
Command Definition utility. See the Open VMS Command Definition, Librarian, 
and M essage Utilities Manual for more information. 

14.3 Displaying Symbols 

The SHOW SYMBOL command displays the values of symbols. To display the 
value of a particular symbol, enter the SHOW SYMBOL command followed by 
the name of the symbol. For example: 

$ SHOW SYMBOL PR 

PR*INT = " PRINT /CONFIRM/ COP IES=2/QUEUE=DOC$LNO 3 /NOTIFY/RE START " 

To display the value of a particular global symbol, include the /GLOBAL qualifier. 
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The SHOW SYMBOL/ALL command displays all local symbols. The command 
SHOW SYMBOL/ALL/GLOBAL displays all global symbols. 

Note that when a symbol has an integer value, the SHOW SYMBOL command 
displays the value in decimal, hexadecimal, and octal notation. For example: 

$ SHOW SYMBOL TOTAL 

TOTAL =4 Hex = 00000004 Octal = 00000000004 

14.4 Deleting Symbols 

The DELETE/SYMBOL command deletes a symbol. To delete a global symbol, 
include the /GLOBAL qualifier. For example, to delete the global symbol TEMP, 
enter the following command: 

$ DELETE/SYMBOL/GLOBAL TEMP 

14.5 Using a Symbol as a Value for Another Symbol 

After you define a symbol, you can use it as part of the definition of another 
symbol. DCL interprets a symbol as a character string or a number, depending 
on the context in which you use the symbol. For example, suppose you assign the 
integer value 3 to the symbol COUNT, as follows: 

S COUNT = 3 

You can then use the value of COUNT in other assignment statements. I n the 
following example, the value of COUNT is added to 1: 

$ TOTAL = COUNT + 1 

The result (4) is equated to the symbol TOTAL. 

14.5.1 Concatenating Symbols 

You can concatenate several symbols to create a long character string by using 
the plus sign ( +). For example: 

S DAYl = "Saturday, " 

$ DAY2 = "Sunday" 

$ WEEKEND = DAYl + DAY2 
$ SHOW SYMBOL WEEKEND 

WEEKEND = "Saturday, Sunday" 

You can also concatenate two or more symbols by placing apostrophes ( ') around 
each symbol name. For example: 

$ NAME = "MYFILE" 

$ TYPE = ".DAT" 

$ PRINT 'NAME" TYPE' 

The PRI NT command prints a copy of MYFI LE.DAT. 

For more information on requesting symbol substitution, see Section 14.9.1.1. 
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14.5.2 Including Symbols in String Assignments 

To include a local symbol in a string assignment, use a colon and an equal sign 
(:=). To include a global symbol in a string assignment, use a colon and two equal 
signs (:==). For either type of symbol (local or global), enclose the symbol in 
apostrophes (' '). Otherwise, DCL will not recognize it as a symbol. The following 
example includes the symbol COUNT in a string assignment statement: 

$ BARK := P' COUNT' 

In a previous example, COUNT was assigned the integer value 3. In this 
example, COUNT is converted to a string value and appended to the character P. 
The local symbol BARK now has the value P3. 

If you define a null character string for a symbol, that symbol has a value of 0 as 
shown in the following example: 

$ A = "" 

$ B = 2 
$ C = A + B 
$ SHOW SYMBOL C 

C = 2 Hex = 00000002 Octal = 00000000002 

14.6 Using Symbols to Store and Manipulate Data 

You can use symbols as variables in command procedures. Variables hold values 
that you calculate or assign as something other than a literal value. For example, 
you might assign the value of a lexical function to a variable or read the value of 
a file record into a variable. 

An expression is a combination of values. In command procedures, expressions 
are used in symbol assignment statements (on the right side of the equal sign), in 
IF statements, in WRITE commands, and as arguments for lexical functions. 

When you define a symbol, the left side of the assignment statement defines the 
symbol name; the right side of the assignment statement contains an expression. 
Each value (also called an operand) in an expression can be connected to another 
value by an operator. DCL evaluates the expression and assigns the result to 
the symbol. I n the following example, the local symbol BARK is equated to an 
expression that adds three numbers: 

$ BARK =1+2+3 

The operands are 1, 2, and 3. The operator is the plus sign ( +). 

In the preceding example, the evaluated expression is an integer, so the symbol 
has an integer value. If an expression is evaluated as a character string, then the 
symbol has a string value. 

The following sections describe how to use character string expressions, numeric 
expressions, and logical expressions. 

14.6.1 Using Character String Values and Expressions 

A character string can contain any characters that can be printed. Appendix B 
includes tables of the ASCI I character set and the DEC Multinational character 
set. These tables list characters you can include in a character string. 
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Characters fall into three main categories: 

• Alphanumeric characters 

The uppercase letters A to Z, lowercase letters a to z, digits 1 to 9, dollar sign 
($), underscore (_), and hyphen (-). 

• Special characters 

All other characters that can be displayed or printed: exclamation point ( ! ), 
quotation marks ( " ), number sign (#), and so on. 

• Nonprintable characters 

All characters that cannot be printed or displayed. In general, nonprintable 
characters are ignored for display and print purposes. However, several 
nonprintable characters serve control functions as follows: 


Character Function 

HT Starts printing or typing at the next horizontal tab 

LF Starts printing or typing on the next line 

F F Starts pri nti ng or typi ng at the top of the next page 

CR Starts printing or typing at the first space on the same line 

ESC I ntroduces a terminal escape sequence 

SP I nserts one space 

You can define a character string by enclosing it in quotation marks ( " " )■ In this 
way, alphabetic case and spaces are preserved when the symbol assignment is 
made. Note the following: 

• To include quotation marks ( " ) within a string, type two consecutive 
quotation marks. For example: 

$ PROMPT = "Type ""YES"" or ""NO 

$ SHOW SYMBOL PROMPT 

PROMPT = "Type "YES" or "NO"" 

• To continue a character string over two lines, use a plus sign (for string 
concatenation) and a hyphen (for continuation). For example: 

$ HEAD = "MONTHLY REPORT FOR" + - 
_$ " DECEMBER 1994" 

$ SHOW SYMBOL HEAD 

HEAD = "MONTHLY REPORT FOR DECEMBER 1994" 

You cannot use the hyphen continuation character within a quoted character 
string. 

A character string expression can contain character strings, lexical functions 
that are evaluated as character strings, or symbols that have character string 
values. When you use a character string in an expression, you must enclose it 
in quotation marks ( " " ). If you do not use quotation marks, DCL processes the 
string as a symbol. 
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Character string expressions combine the following values (called string 
operands): 

• Character strings that must appear in quotation marks. For example: 

S TEMP = "CAT" 

• Symbols that represent character strings. For example: 

S TOPIC = "THE" + TEMP 

In the preceding example, the symbol TEMP represents the character string 
"CAT." The symbol TOPIC is a concatenation of the character string 'THE" 
and the character string that the symbol TEMP represents ("CAT"). The 
result is "THE CAT." 

• Lexical functions that are evaluated as character strings. For example: 

$ COUNT = F$STRING (65) 

If you perform an operation or comparison between a character string and a 
number, DCL converts the character string to a number. 

String operands can be added (string concatenation), subtracted (string 
reduction), compared, or replaced with other character strings as described 
in the following subsections. 

14.6.1.1 Adding and Subtracting Character Strings 

You can specify the following character string operations: 

• Concatenation— The plus sign concatenates two character strings. For 
example: 

$ COLOR = "light brown" 

S WEIGHT = "30 lbs." 

S DOG2 = "No tag, " + COLOR + ", " + WEIGHT 
$ SHOW SYMBOL DOG2 

DOG2 = "No tag, light brown, 30 lbs." 

• Reduction— The minus sign removes the second character string from the first 
character string. For example: 

S SHOW SYMBOL DOG2 

DOG2 = "No tag, light brown, 30 lbs." 

$ DOG2 = DOG2 - ", 30 lbs." 

$ SHOW SYMBOL DOG2 

DOG2 = "No tag, light brown" 

If the second character string occurs more than once in the first character 
string, only the first occurrence of the string is removed. 

14.6.1.2 Comparing Character Strings 

When you compare two character strings, the strings are compared character 
by character. Strings of different lengths are not equal (for example, “dogs” is 
greater than "dog”). 

The comparison criteria are the ASCI I values of the characters. Under these 
criteria, the digits 0 to 9 are less than the uppercase letters A to Z, and the 
uppercase letters A to Z are less than the lowercase letters a to z. A character 
string comparison ends when either of the following conditions is true: 

• All the characters have been compared, in which case the strings are equal. 

• The first mismatch occurs. 
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Table 14-2 lists different types of string comparisons. In the examples, assume 
that the symbol LAST_NAME has the value "WH ITFI ELD." 


Table 14-2 String Comparisons 


Comparison 

Operator 

Description 

Example 

Equal to 

.EQS. 

Compares one 
character string to 
another for equality. 

$ TEST_NAME = LAST_NAME .EQS. "Hill” 

$ SHOW SYMBOL TEST_NAME 

TEST_NAME =0 ... 

Is evaluated as 0 (False); the value of the symbol 
LAST_NAME does not equal the literal "HILL." 

Greater than 
or equal to 

.GES. 

Compares one 
character string to 
another for greater or 
equal value in the first 
specified string. 

$ TEST_NAME = LAST_NAME .GES. "HILL” 

$ SHOW SYMBOL TEST_NAME 

TEST_NAME =1 ... 

Is evaluated as 1 (True); the value of the symbol 
LAST NAME is greater than or equal to the literal 
"HILL." 

Greater than 

.GTS. 

Compares one 
character string to 
another for a greater 
value in the first 
specified string. 

$ TEST_NAME = LAST_NAME .GTS. "HILL" 

$ SHOW SYMBOL TEST_NAME 

TEST_NAME =1 ... 

Is evaluated as 1 (True); the value of the symbol 
LAST_NAME is greater than the literal "HILL." 

Less than or 
equal to 

.LES. 

Compares one 
character string to 
another for a lesser or 
equal value in the first 
specified string. 

$ TEST_NAME = LAST_NAME .LES. "HILL" 

$ SHOW SYMBOL TEST_NAME 

TEST_NAME =0 ... 

Is evaluated as 0 (False); the value of the symbol 
LAST NAM E is not less than or equal to the literal 
"HILL." 

Less than 

.LTS. 

Compares one 
character string to 
another for a lesser 
value in the first 
specified string. 

$ TEST_NAME = LAST_NAME .LTS. "HILL” 

$ SHOW SYMBOL TEST_NAME 

TEST_NAME =0 ... 

Is evaluated as 0 (False); the value of the symbol 
LAST_NAME is not less than the literal "HILL." 

Not equal 

.NES. 

Compares one 
character string to 
another for inequality. 

$ TEST_NAME = LAST_NAME .NES. "HILL" 

$ SHOW SYMBOL TEST_NAME 

TEST_NAME =1 ... 

Is evaluated as 1 (True); the value of the symbol 
LAST_NAME does not equal the literal "HILL." 
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14.6.1.3 Replacing Substrings 

You can replace part of a character string with another character string by 
specifying the position and size of the replacement string. The format for local 
symbols is: 

symbol-name[offset,size] := replacement-string 
The format for global symbols is: 
symbol-name[offset,size] :== replacement-string 
The elements are as follows: 

offset An integer that indicates the position of the replacement string relative to the 
first character in the original string. An offset of 0 means the first character in 
the symbol, an offset of 1 means the second character, and so on. 

size An integer that indicates the length of the replacement string. 

To replace substrings, observe the following rules: 

• The square brackets are required notation. No spaces are allowed between 
the symbol name and the left bracket. 

• I nteger values for size and offset values can range from 0 to 768. 

• The replacement-string must be a character string. 

In the following example, the first assignment statement gives the symbol A the 
value PACKRAT. The second statement specifies that M USK replace the first four 
characters in the value of A. The result is that the value of A becomes MUSKRAT. 

$ A := PACKRAT 
$ A [ 0 , 4 ] := MUSK 
$ SHOW SYMBOL A 
A = "MUSKRAT" 

The symbol name you specify can be undefined initially. The assignment 
statement creates the symbol name and if necessary, provides leading or trailing 
spaces in the symbol value. For example: 

$ B [4, 3] := RAT 

If the symbol B does not have a previous value, it is given a value of four leading 
spaces followed by RAT. 

You can also specify an offset and size to create a symbol that represents a blank 
line. For example, to assign a value of 80 blank spaces to the symbol LINE, enter 
the following command: 

$ LINE [0,80] := " " 

Lining up records in columns makes a list easier to read and sort. You can use 
this format to specify how you want data to be stored. For example: 

$ DATA[0, 15] := 'NAME' 

$ DATA [17, 1] := 'GRADE' 

The first statement fills in the first 15 columns of DATA with whatever value 
NAME has. The second statement fills in column 18 with whatever value GRADE 
has. Columns 16 and 17 contain blanks. 
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14.6.2 Using Numeric Values and Expressions 

A number can have the following values: 

• Decimal— The ASCI I characters 0 to 9 

• Hexadecimal— The ASCI I characters 0 to 9 and A to F 

• Octal— The ASCI I characters 0 to 7 

The number you assign to a symbol must be in the range -2147483648 to 
2147483647 (decimal). An error is not reported if a number outside this range is 
specified or calculated but an incorrect value results. 

At DCL command level and within command procedures, specify a number as 
follows: 

• Positive numbers 

Specify a positive number by typing the appropriate digits. The following 
example assigns the number 13 to the symbol DOG_COUNT: 

$ D0G_C0UNT = 13 
$ SHOW SYMBOL DOGJCOUNT 

D0G_C0UNT = 13 Hex = 0000000D Octal = 00000000015 

• Negative numbers 

Precede a negative number with a minus sign (-), as in the following example: 

$ BALANCE = -15237 
$ SHOW SYMBOL BALANCE 

BALANCE = -15237 Hex = FFFFC47B Octal = 37777742173 

• Radix 

Specify a number in a radix other than decimal by preceding the number 
(but not the minus sign) with %X for hexadecimal numbers and %0 for octal 
numbers. For example: 

$ DOGJCOUNT = %XD 
$ SHOW SYMBOL DOGJCOUNT 

DOGJCOUNT = 13 Hex = 0000000D Octal = 00000000015 

$ BALANCE = -%X3B85 
$ SHOW SYMBOL BALANCE 

BALANCE = -15237 Hex = FFFFC47B Octal = 37777742173 

• Fractions 

A number cannot include a decimal point. In calculations, fractions are 
truncated. For example, 8 divided by 3 equals 2. 

Numbers are stored internally as signed 4-byte integers, called longwords; 
positive numbers have values of 0 to 2147483647 and negative numbers have 
values of 4294967296 minus the absolute value of the number. The number 
-15237, for example, is stored as 4294952059. Negative numbers are converted 
back to minus-sign format for ASCII or decimal displays; however, they are not 
converted back for hexadecimal and octal displays. For example, the number 
-15237 appears in displays as hexadecimal FFFFC47B (decimal 4294952059) 
rather than hexadecimal -00003B85. 

Numbers are stored in text files as a series of digits using ASCII conventions (for 
example, the digit 1 has a storage value of 49). 
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In a numeric expression, the values involved must be literal numbers (such 
as 3) or symbols with numeric values. In addition, you can use a character 
string that represents a number (for example, "23" or "-51"). If you perform an 
operation or comparison between a number and a character string, DCL converts 
the character string to a number. 

Numeric expressions combine the following values (called integer operands): 

• Integers. For example: 

$ COUNT = 1 

• Lexical functions that are evaluated as integers. For example: 

S B = F$INTEGER(”-9" + 23) 

• Symbols that have integer values. For example: 

$ A = B - 6 

I n the preceding example, the symbol B represents the integer value returned 
by the F $1 NTEGER function (-923). 

These integer operands can be connected by arithmetic, logical, and comparison 
operators, as described in the following sections. 

14.6.2.1 Performing Arithmetic Operations 

You can specify the following arithmetic operations: 

• Multiplication 

The asterisk (*) multiplies two numbers. For example: 

S BALANCE = 142 * 14 
$ SHOW SYMBOL BALANCE 

BALANCE = 1988 Hex = 000007C4 Octal = 00000003704 

• Division 

The slash (/) divides the first specified number by the second specified 
number. For example: 

$ BALANCE = BALANCE / 14 
S SHOW SYMBOL BALANCE 

BALANCE = 142 Hex = 0000008E Octal = 00000000216 

If a number does not divide evenly, the remainder is lost. No rounding takes 
place. 

• Addition 

The plus sign ( +) adds two numbers. For example: 

S BALANCE = BALANCE +37 
S SHOW SYMBOL BALANCE 

BALANCE = 179 Hex = 000000B3 Octal = 00000000263 

• Subtraction 

The minus sign (-) subtracts the second specified number from the first 
specified number. For example: 

$ BALANCE = BALANCE - 15416 
$ SHOW SYMBOL BALANCE 

BALANCE = -15237 Hex = FFFFC47B Octal = 00000142173 
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• Unary plus and minus 

The plus and minus signs change the sign of the number they precede. For 
example: 

$ BALANCE = -(-142) 

$ SHOW SYMBOL BALANCE 

BALANCE = 142 Hex = 0000008E Octal = 00000000216 

14.6.2.2 Comparing Numbers 

Table 14-3 lists different types of numeric comparisons. I n the examples, assume 
that the symbol BALANCE has the value — 15237. 


Table 14-3 Numeric Comparisons 

Comparison Operator Description Example 


Equal to .EQ. 


Greater than or .GE. 
equal to 


Greater than .GT. 


Less than or .LE. 
equal to 


Less than .LT. 


Compares one number 
to another for equality. 

$ TEST_BALANCE = BALANCE .EQ. -15237 
$ SHOW SYMBOL TEST_BALANCE 
TEST_BALANCE =1 ... 

Is evaluated as 1 (True); BALANCE equals 
-15237. 


Compares one number 
to another for a greater 
or equal value in the 
first number. 


Compares one number 
to another for a greater 
value in the first 
number. 


Compares one number 
to another for a lesser or 
equal value in the first 
number. 


Compares one number 
to another for a lesser 
value in the first 
number. 


$ TEST_BALANCE = BALANCE .GE. -15237 
$ SHOW SYMBOL TEST_BALANCE 
TEST_BALANCE =1 ... 

Is evaluated as 1 (True); BALANCE is 
greater than or equal to -15237. 


$ TEST_BALANCE = BALANCE .GT. -15237 
$ SHOW SYMBOL TEST_BALANCE 
TEST_BALANCE =0 ... 

Is evaluated as 0 (False); BALANCE is not 
greater than -15237. 


$ TEST_BALANCE = BALANCE .LE. -15237 
$ SHOW SYMBOL TEST_BALANCE 
TEST_BALANCE =1 ... 

Is evaluated as 1 (True); BALANCE is less 
than or equal to -15237. 


$ TEST_BALANCE = BALANCE .LT. -15237 
$ SHOW SYMBOL TEST_BALANCE 
TEST_BALANCE =0 ... 


Is evaluated as 0 (False); BALANCE is not 
less than -15237. 


(continued on next page) 
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Table 14-3 (Cont.) Numeric Comparisons 


Comparison 

Operator 

Description 

Example 

Not equal to 

.NE. 

Compares one number 
to another for inequality. 

$ TES IMBALANCE = BALANCE .NE. -15237 
$ SHOW SYMBOL TEST_BALANCE 

TEST_BALANCE =0 ... 

Is evaluated as 0 (False); BALANCE equals 
-15237. 


14.6.2.3 Performing Numeric Overlays 

You can perform binary (bit-level) overlays of the current symbol value by using a 
special format of the assignment statement. For local symbols, the format is: 

symbol-name[bit-position,size] = replacement-expression 

For global symbols, the format is: 

symbol-name[bit-position,size] == replacement-expression 

The elements are as follows: 

bit-position An integer that indicates the location relative to bit 0 at which the 

overlay is to occur. 

size An integer that indicates the number of bits to be overlaid. 

To use numeric overlays, observe the following rules: 

• The square brackets ([]) are required notation. No spaces are allowed 
between the symbol name and the left bracket. 

• Literal values are assumed to be decimal. 

• The maximum length for size is 32 bits. 

• Replacement-expression must be a numeric expression. 

• When symbol-name is either undefined or defined as a string, the result of 
the overlay is a string. Otherwise, the result is an integer. 

The following example defines the symbol BELL as the value 7. The low-order 
byte of BELL has the binary value 00000111. By changing the 0 at offset 5 to 
1 (beginning with 0, count bits from right to left), you create the binary value 
00100111 (decimal value 39). 

$ BELL = 7 
$ BELL [5,1] = 1 
$ SHOW SYMBOL BELL 

BELL = 39 Hex = 00000027 Octal = 00000000047 

14.6.3 Using Logical Values and Expressions 

Some operations interpret numbers and character strings as logical data with 
values as follows: 

• True 

A number has a logical value of true if it is odd (that is, the low-order bit is 
1). A character string has a logical value of true if the first character is an 
uppercase or lowercase T or Y. 


14-14 


Symbols: Defining Commands and Expressions 
14.6 Using Symbols to Store and Manipulate Data 


• False 

A number has a logical value of false if it is even (that is, the low-order bit is 
0). A character string has a logical value of false if the first character is not 
an uppercase or lowercase T or Y. 

In both of the following examples, DOG_COUNT is assigned the value 13. IF 
STATUS means if the logical value of STATUS is true. 

$ STATUS = 1 

$ IF STATUS THEN D0G_C0UNT = 13 

$ STATUS = "TRUE" 

$ IF STATUS THEN D0GJS0UNT = 13 

A logical operation affects all the bits in the number being acted upon. The 
values for logical expressions are integers, and the result of the expression is 
an integer as well. If you specify a character string value in a logical expression, 
the string is converted to an integer before the expression is evaluated. 

Typically, you use logical expressions to evaluate the low-order bit of a logical 
value; that is, to determine whether the value is true or false. You can specify the 
following logical operations: 

• Not 

The operator .NOT. reverses the bit configuration of a logical value. A true 
value becomes false and a false value becomes true. The following example 
reverses a true value to false. The expression is evaluated as -2; the value is 
even and is therefore false: 

$ SHOW SYMBOL STATUS 

STATUS =1 Hex = 00000001 Octal = 00000000001 
$ STATUS = .NOT. STATUS 
$ SHOW SYMBOL STATUS 

STATUS = -2 Hex = FFFFFFFE Octal = 37777777776 

• And 

The operator .AND. combines two logical values as follows: 


Bit Level 

Entity Level 

1 .AND. 1=1 

true .AND. true =true 

1 .AND. 0=0 

true .AND. false = false 

0 .AND. 1=0 

false .AND. true = false 

0 .AND. 0=0 

false .AND. false = false 


The following example combines a true value and a false value to produce a 
false value: 

$ STATl = "TRUE" 

$ STAT2 = "FALSE" 

$ STATUS = STATl .AND. STAT2 
$ SHOW SYMBOL STATUS 

STATUS =0 Hex = 00000000 Octal = 00000000000 
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• Or 

The operator .OR. combines two logical values as follows: 


Bit Level 

Entity Level 

1 .OR. 1=1 

true .OR. true =true 

1 .OR. 0=1 

true .OR. false =true 

0 .OR. 1=1 

false .OR. true =true 

0 .OR. 0=0 

false .OR. false = false 


The following example combines a true value and a false value to produce a 
true value: 

$ STATl = "TRUE" 

$ STAT2 = "FALSE" 

S STATUS = STATl .OR. STAT2 
S SHOW SYMBOL STATUS 

STATUS =1 Hex = 00000001 Octal = 00000000001 

The following tables demonstrate the results of logical operations on a bit-by-bit 
basis and a number-by-number basis. In logical operations, a character string 
beginning with an uppercase or lowercase T or Y is treated as the number 1; a 
character string beginning with any other character is treated as the number 0. 

I n logical operations, odd numbers are true and even numbers and zero are false. 


Given That: 

Bit A 

Bit B 

The Results Are: 

.NOT. A A .AND. B 

A .OR. B 

1 

1 

0 

1 

1 

1 

0 

0 

0 

1 

0 

1 

1 

0 

1 

0 

0 

1 

0 

0 


Given That: The Results Are: 


Number A 

Number B 

.NOT. A 

A .AND. B 

A .OR. B 

odd 

odd 

even 

odd 

odd 

odd 

even 

even 

even 

odd 

even 

odd 

odd 

even 

odd 

even 

even 

odd 

even 

even 


14.6.4 Using Values Returned by Lexical Functions 

Typically used in command procedures, lexical functions retrieve information 
from the system, including information about system processes, batch and print 
queues, and user processes. You can also use lexical functions to manipulate 
character strings and translate logical names. When you assign a lexical function 
to a symbol, the symbol is equated to the information returned by the lexical 
function (for example, a number or character string). At DCL level, you can 
then display that information with the DCL command SHOW SYMBOL. In a 
command procedure, the information stored in the symbol can be used later in 
the procedure. Seethe OpenVMS DCL Dictionary for a description of each lexical 
function. 
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To use a lexical function, specify the name of the lexical function (which always 
begins with F$) and its argument list. Use the following format: 

F$function-name(args[,...]) 

The argument list follows the function name with any number of intervening 
spaces and tabs. When you use a lexical function, observe the following rules: 

• Enclose the argument list in parentheses. 

• Within the list, specify arguments in exact order and separate them with 
commas; even if you omit an optional argument, do not omit the comma. 

• If no arguments are required, type an empty set of parentheses. 

• Follow the rules for writing expressions: enclose character strings in 
quotation marks; do not enclose integers, symbols, and lexical functions 
in quotation marks. 

Use lexical functions the same way you would use character strings, integers, and 
symbols. When you use a lexical function in an expression, DCL automatically 
evaluates the function and replaces the function with its return value. For 
example: 

S SUM = F$LENGTH( "BUMBLEBEE") + 1 
$ SHOW SYMBOL SUM 

SUM = 10 Hex = 0000000A Octal = 00000000012 

The F$LENGTFI function returns the length of the value specified as 
BUMBLEBEE as its argument. DCL automatically determines the return 
value (9) and uses this value to evaluate the expression. Therefore, the result of 
the expression (9 + 1) is 10 and this value is assigned to the symbol SUM . 

Note that each lexical function returns information as either an integer or a 
character string. In addition, you must specify the arguments for a lexical 
function as either integer or character string expressions. 

For example, the F$LENGTH function requires an argument that is a character 
string expression and it returns a value that is an integer. In the previous 
example, the argument "BUMBLEBEE" is a character string expression and the 
return value (9) is an integer. 

The following examples show different ways you can specify the argument for 
the F$LENGTFI function. In each example, the argument is a character string 
expression. The first example shows a symbol that is used as an argument: 

$ BUG = "BUMBLEBEE” 

$ LEN = F$LENGTH (BUG) 

$ SHOW SYMBOL LEN 

LEN =9 Hex = 00000009 Octal = 00000000011 

When you use the symbol BUG as an argument, do not place quotation 
marks around it. The lexical function automatically substitutes the value 
"BUM BLE BEE" for BUG, determines the length, and returns the value 9. 

This example shows an argument that contains both a symbol and a character 
string: 
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$ BUG = "BUMBLEBEE" 

$ LEN = F$LENGTH (BUG) 

$ SHOW SYMBOL LEN 

LEN =9 Hex = 00000009 Octal = 00000000011 
$ LEN = F$LENGTH (BUG + "S") 

$ SHOW SYMBOL LEN 

LEN = 10 Hex = 0000000A Octal = 00000000012 

The symbol BUG is not enclosed in quotation marks but the string "S" is. The 
argument must be evaluated before the F$LENGTH function can determine 
the length. The value represented by the symbol BUG ("BUMBLEBEE") is 
concatenated with the string "S"; the result is "BUMBLEBEES". The F$LENGTH 
function determines the length of the string "BUMBLEBEES" and returns the 
value 10. 

The next example uses another lexical function as the argument for the 
F$LENGTH function. The F$DI RECTORY function returns the name of your 
current default directory, including the square brackets. In this example, the 
current default directory is [SALMON], 

$ LEN = F$LENGTH (F$DIRECTORY ( ) ) 

$ SHOW SYMBOL LEN 

LEN =8 Hex = 00000008 Octal = 00000000010 

Do not place quotation marks around the F $D I RECTORY function when it is 
used as an argument; the function is automatically evaluated. The result of the 
F$DIRECTORY function must be returned before the F$LENGTH function can 
determine the length. Then, the F$LENGTFI function determines the length of 
your default directory, including the square brackets. 

You can use a lexical function in any position that you can use a symbol. In 
positions where symbol substitution must be forced by enclosing the symbol in 
apostrophes (see Section 14.9), lexical function evaluation must be forced by 
placing the lexical function within apostrophes. Lexical functions can also be 
used as argument values in other lexical functions. 

14.6.5 Determining the Order of Operations 

An expression can contain any number of operations and comparisons. The 
following table lists the operators in the order in which they are evaluated 
if there are two or more operators in an expression. The operators are listed 
from highest to lowest precedence; that is, operators at the top of the table are 
performed before operators at the bottom. 


Precedence 

Operation 

7 

Unary plus (+) and minus (- ) 

6 

Multiplication (*) and division (/) 

5 

Addition (concatenation) and subtraction (reduction) 

4 

All numeric and character comparisons 

3 

Logical NOT operations 

2 

Logical AND operations 

1 

Logical OR operations 


If an expression contains operators that have the same order of precedence, the 
operations are performed from left to right. You can override the normal order of 
precedence (the order in which operation and comparison would be evaluated) by 
placing operations to be performed first in parentheses. For example: 
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$ RESULT = 4 * (6+2) 

$ SHOW SYMBOL RESULT 

RESULT = 32 Hex = 00000020 Octal = 00000000040 

I n this example, the parentheses force the addition to be performed before the 
multiplication. Without the parentheses, the multiplication is performed first and 
the result is 26. Parentheses can also be nested. 

14.6.6 Evaluating the Data Type of a Symbol 

The result of DCL's evaluation of a symbol is either a character string or an 
integer value. The data type (character or integer) of a symbol is determined by 
the data type of the value currently assigned. The data type is not permanent: 
if the value changes data type, as in the following example, the symbol changes 
data type. In the following example, the local symbol NUM is first assigned a 
character value and then converted to an integer value when assigned an integer 
expression: 

$ NUM = "ABC" 

$ NUM = 2 + 5 

Thus, an expression has either an integer or a string value, depending on the 
types of values and the operators used. Table 14-4 summarizes how DCL 
evaluates expressions. The first column lists the different values and operators 
that an expression might contain. The second column tells, for each case, what 
the entire expression is equated to. Within the table any value stands for a string 
or an integer. 


Table 14-4 Determining the Value of an Expression 


Expression 

Resulting 

Value Type 

1 nteger value 

1 nteger 

String value 

String 

Integer lexical function 

1 nteger 

String lexical function 

String 

1 nteger symbol 

1 nteger 

String symbol 

String 

+, -, or .NOT. any value 

1 nteger 

Any value .AND. or .OR. any value 

1 nteger 

String +or — string 

String 

Integer +or — any value 

1 nteger 

Any value +or — integer 

1 nteger 

Any value * or / any value 

1 nteger 

Any value (string comparison) any value 

1 nteger 

Any value (numeric comparison) any value 

1 nteger 


14.6.7 Converting Value Types in an Expression 

All the operands in an expression must be of the same value data type before 
DCL can evaluate the expression. Values either have string or integer data types. 
String data includes character strings, symbols with string values, and lexical 
functions that return string values. Integer data includes integers, symbols 
with integer values, and lexical functions that return integer values. When an 
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expression contains both number and string operands, DCL either converts all 
strings to integers or all integers to strings. 

In general, if you use both string and integer values, the string values are 
converted to integers. The only exception is when DCL performs string 
comparisons. I n these comparisons, integers are converted to strings. 

In addition, the following lexical functions let you determine or change the value 
of an expression: 

• F $TY PE— Determines the current value type of a symbol 

• F$l NTEGER— Converts a string expression to an integer value 

• F$STRI NG— Converts an integer expression to a string value 

The following sections describe how DCL converts an integer to a string and vice 
versa. 

14.6.7.1 Converting Strings to Integers 

Character strings are converted to integers in the following ways: 

• Strings containing numbers are converted to their integer values. For 
example, the string "45" is converted to the integer 45. 

• If a character string begins with T, t, Y, or y, it is converted to the integer 1. 

• If a string begins with any other letter, it is converted to the integer 0. 

The following table shows how strings are converted to integer values: 


String 

Resulting Integer 

"123" 

123 

"12XY " 

0 (False) 

'Test" 

1 (True) 

"hello" 

0 (False) 


14.6.7.2 Converting Integers to Strings 

When integers are converted to character strings, the resulting string contains 
numbers that correspond to the integer value. The following table shows how 
integers are converted to string values: 


Integer 

Resulting String 

123 

"123" 

1 

"1" 

0 

"0" 


14.7 Understanding Symbol Tables 

Symbols are stored in the following tables, which are maintained by the operating 
system: 

• Local symbol table 
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DCL maintains a local symbol table for your main process and for every 
command level that you create when you execute a command procedure, use 
the CALL command, or submit a batch job. When you create a local symbol, 
DCL places the symbol in the local symbol table for the current command 
level. As long as the command level is active, DCL maintains the local symbol 
table for that command level; when a command level is no longer active, its 
local symbol table (and all the symbols it contains) is deleted. See Chapter 17 
for more information about processes, command procedures, and batch jobs. 

I n addition to the local symbols you create, a local symbol table contains eight 
symbols that are maintained by DCL. These symbols, named PI, P2, and so 
on through P8, are used for passing parameters to a command procedure. 
Parameters passed to a command procedure are regarded as character 
strings. Otherwise, PI to P8 are defined as null character strings ( nn ). They 
are stored in the local symbol table. 

• Global symbol table 

DCL maintains only one global symbol table for the duration of a process and 
places all global symbols in that table. In addition to the global symbols you 
create, the global symbol table contains the reserved global symbols described 
in the following table. These global symbols give you status information on 
your programs and command procedures as well as on system commands and 
utilities. 


Reserved 

Global 

Symbols 

Definition 

$STATU S 

The condition code returned by the most recently executed command. 
The symbol $STATUS conforms to the format of an OpenVMS 
operating system message code. Applications programs can set the 
value of the global symbol $STATUS by including a parameter value 
to the EXIT command. The system uses the value of $STATUS to 
determine which message, if any, to display and whether to continue 
execution at the next higher command level. The value of the lowest 
three bits in $STATUS is placed in the global symbol $SEVERITY. 

$SEVE RITY 

The severity level of the condition code returned by the most recently 
executed command. The symbol $SE VERITY, which is equal to the 
lowest three bits of $STATUS, can have the following values: 


0 Warning 

1 Success 

2 Error 

3 Information 

4 Severe (fatal) error 

$RE START 

Has the value TRUE if a batch job was restarted after it was 
interrupted by a system failure. Otherwise, $RESTART has the 
value FALSE. 


When the command interpreter determines the value of a symbol, it searches 
symbol tables in the following order: 

1. The local symbol table for the current command level 

2. Local symbol tables for each previous command level, searching backwards 
from the current level 

3. The global symbol table 
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14.8 Masking the Value of Symbols 

By default, all symbols (both global and local) defined in an outer command 
procedure level are accessible to inner procedure levels. However, you can isolate 
the local or global symbols in a command procedure from the symbols defined 
in other command procedures by using the SET SYMBOL command. The SET 
SYMBOL command masks the values of local and global symbols without deleting 
them. Thus, if a command procedure executes another command procedure, 
you can use the same symbol names in both procedures if you specify the SET 
SYMBOL command in the second procedure. 

The SET SYMBOL command also controls whether DCL attempts to translate the 
verb string (the first word on the command line) as a symbol before processing the 
line. The default behavior is that the translation is attempted. The advantage 
to changing this behavior is that a command procedure is not affected by 
outer-procedure-level environments when it invokes a command. 

The symbol scope is different for local and global symbols, as follows: 

• Local symbols are procedure-level dependent. If you define a local symbol in 
an outer procedure level, the symbol can be read (but not written to) at any 
inner procedure level. If you assign a value to a symbol that is local to an 
outer procedure level, a new symbol is created at the current procedure level. 
However, the symbol in the outer procedure level is not modified. 

The SET SYMBOL/SCOPE=l\IOLOCAL command causes all local symbols 
defined at an outer procedure level to be inaccessible to the current procedure 
level and any inner levels. For example, if you specify SET SYMBOL 
/SCOPE =NOLOCAL at procedure levels 2 and 4: 

- Procedure level 2 can read and write to level 2 local symbols only. 

- Procedure level 3 can read (but not write to) level 2 local symbols. Level 
3 can also read and write to level 3 local symbols. 

- Procedure level 4 can read and write to level 4 local symbols only. 

• Global symbols are procedure-level independent. The current global symbol 
scoping context is applied subsequently to all procedure levels. 

The /SCOPE =NOGLOBAL qualifier causes all global symbols to become 
inaccessible for all subsequent commands until either the /SCOPE ^GLOBAL 
qualifier is specified or the procedure exits to a previous level at which global 
symbols were accessible. In addition, specifying the /SCOPE =NOGLOBAL 
qualifier prevents you from creating any new global symbols until the 
/SCOPE=GLOBAL qualifier is specified. 

When you exit a procedure level to return to a previous procedure, the symbol 
scoping context from the previous level is restored for both local and global 
symbols. 

To display the current, general symbol scoping state, use the lexical function 
F$ENVI RONMENT("SYMBOL_SCOPE"). To display the current verb scoping 
state, use the lexical function F$ENVI RONMENT("VERB_SCOPE"). 


14-22 


Symbols: Defining Commands and Expressions 
14.9 Understanding Symbol Substitution 

14.9 Understanding Symbol Substitution 

In certain contexts, DCL uses a string of characters beginning with a letter as 
a symbol name or a lexical function. I n these contexts, DCL tries to replace the 
symbol or lexical function with its value. Replacing a symbol with its current 
value is referred to as symbol substitution. If you use a symbol or lexical function 
in any other context, you must use a substitution operator to request symbol 
substitution. 

DCL automatically evaluates symbols and lexical functions when they are used 
as follows: 

• On the right side of an assignment (=) statement. I n the following example, 
COUNT is automatically recognized and evaluated as a symbol: 

$ TOTAL = COUNT + 1 

• In an argument for a lexical function. For example: 

$ QUERY = "Have we met before?" 

$ LEN = F$ LENGTH (QUERY) + 5 
$ SHOW SYMBOL LEN 

LEN = 27 Hex = 0000001B Octal = 000033 

In the second line, the symbol QUERY is automatically evaluated when it is 
used with the F$LENGTH function. In addition, the F$LENGTH function 
is automatically evaluated because it is on the right side of an assignment 
statement. 

• In a DEPOSIT, EXAMINE, IF, or WRITE command. I n the following example, 
the I F command uses both A and B as symbol names and uses their current 
val ues: 

$ IF A .EQ. B THEN WRITE SYS$OUTPUT "DONE" 

• At the beginning of a command line when the string is not followed by an 
equal sign or a colon. For example: 

$ PDEL = "DELETE SYS$PRINT/ENTRY=" 

$ PDEL 181 

In the second line, the command interpreter automatically replaces PDEL 
with its current value and executes the resulting command. 

• I n the brackets on the left side of an assignment statement when you are 
performing substring substitution or numeric overlays (see Section 14.6.1.3). 
For example: 

$ BELL = 7 
$ BELL [5,1] = 1 
$ SHOW SYMBOL BELL 

BELL = 39 Hex = 00000027 Octal = 00000000047 

In any of these contexts, the command interpreter uses any character string 
beginning with an alphabetic character as a symbol name and any string 
beginning with a number or with the radix operator (%) as a literal numeric 
value. 

To force substitution of a symbol that is not in one of the positions listed, enclose 
the symbol with apostrophes ('), as follows: 

$ TYPE 'B' 
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To force substitution of a symbol within a quoted character string, precede that 
symbol with two apostrophes (') and follow it with a single apostrophe (') as 
follows: 

$ T = "TYPE "B' " 

When processing a command line, DCL replaces symbols with their values in the 
following order: 

• Forced substitution 

From left to right, DCL replaces all strings delimited by apostrophes (or 
double apostrophes for strings within quotation marks). Symbols preceded 
by single apostrophes are translated iteratively; symbols preceded by double 
apostrophes are not. 

• Automatic substitution 

From left to right, DCL evaluates each value in the command line, executing 
it if it is a command and evaluating it if it is an expression. Symbols in 
expressions are replaced by their assigned values; this substitution is not 
iterative. 

The following example demonstrates the effect of the order in which DCL 
substitutes symbols. Define the symbols PN, FILE1, and NUM as follows: 

$ PN = "PRINT/NOTIFY" 

$ FILE1 = " [BOLIVAR] TEST_CASE . TXT" 

$ NUM = 1 

Given the preceding symbol definitions, the following commands print the file 
named [BOLIVAR]TE ST_CASE.TXT: 

$ FILE = "'FILE" NUM' ' " 

$ PN 'FILE' 

In the first command, forced substitution causes NUM to become 1, making 
FILE"NUM' becomeFILEl. If you enter the command SHOW SYMBOL FI LE, 
you see that FILE = " ' F I L E 1' ". 

The second command performs two substitutions. First, 'FILE' is substituted with 
'FI LEI'. 'FI LEI' also requires substitution because it is enclosed in apostrophes 
(' ). Automatic substitution causes FI LEI to become [BOLI VAR]TEST_ 
CASE.TXT. This file name is then appended to the value of PN, which is 
PRI NT/NOTI FY. The resulting string is as follows: 

$ PRINT/NOTIFY [BOLIVAR] TEST_CASE . TXT 

14.9.1 Requesting Symbol Substitution 

You can use a substitution operator to request symbol substitution in places 
where DCL does not usually perform it. DCL accepts two substitution operators: 

• Apostrophe ( ' ) 

• Ampersand ( & ) 

The difference between these two operators is the time when the substitution 
occurs. Symbols preceded by apostrophes are substituted during the first phase 
of DCL command processing; symbols preceded by ampersands are substituted 
during the second phase. For more information on the phases of command 
processing, see Section 14.9.2. 
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14.9.1.1 The Apostrophe (’) 

The apostrophe ( ') is the most frequently used substitution operator. Use it 
to request symbol substitution when you use a symbol in place of a command 
parameter or qualifier. For example: 

$ LIT = "LIGHT. BILLS" 

$ TYPE 'LIT' 

The TYPE command requires a file specification. The apostrophes indicate that 
LIT is a symbol that must be evaluated. If you omit the apostrophes, DCL looks 
for a file called LIT.LI S (.LIS is the default file type for the TYPE command). 

Use the apostrophes to request symbol substitution on the right side of a string 
assignment ( :=) statement. For example: 

$ NAME := REPORT 
$ FILE := 'NAME' .DAT 
$ SHOW SYMBOL FILE 
FILE = " REPORT.DAT " 

The value for NAME is substituted so that FI LE becomesREPORT.DAT. 

To request symbol substitution within a quoted character string, place two 
apostrophes before the symbol name and one apostrophe after it. For example: 

$ MESSAGE = "Creating file "NAME' .DAT" 

If the current value of the symbol NAME is FRED, then MESSAGE has the 
following value: 

Creating file FRED.DAT 

When you use apostrophes to request symbol substitution, you cannot continue 
the line (with the hyphen continuation character) in the middle of the value that 
is being substituted. 

14.9.1.2 The Ampersand (&) 

The ampersand (& ) is also a substitution operator that the command interpreter 
recognizes. I n many cases, the apostrophe and the ampersand perform the same 
function. For example: 

$ TYPE 'NAME' 

$ TYPE &NAME 

In the first command, the command interpreter replaces the symbol NAME with 
its current value during the first phase of command processing (scanning). The 
second command replaces the symbol NAME with its current value during the 
second phase of command processing (parsing). The result is the same, even 
though the methods are different. 

Ampersands are most effective as substitution operators when they are used with 
apostrophes to affect the order in which substitution is performed. For example: 

$ PI = "FRED.DAT" 

$ COUNT = 1 
$ TYPE SP' COUNT' 

First, the command interpreter evaluates the symbol enclosed by apostrophes 
('COUNT'). The result is as follows: 

TYPE &P1 
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Second, the command interpreter evaluates the symbol preceded by an ampersand 
(PI). The result is as follows: 

TYPE FRED . DAT 

Suppose you had used apostrophes with both P and COUNT, as in the following 
example: 

$ TYPE 'P" COUNT' 

Working left to right, the command interpreter attempts to evaluate P. Because P 
is not a defined symbol, DCL gives it a null value. Next, it evaluates the symbol 
COUNT. The result is as follows: 

TYPE 1 

The action the command interpreter takes when a symbol is undefined depends 
on the context of the command. For more information, see Section 14.9.4. 

In the following example, A is equated to the current value of B: 

$ B = "MYFILE.DAT " 

$ A = "&B" 

$ TYPE 'A' 

The ampersand (& ) does not cause symbol substitution when it is used inside 
quotation marks ( " " ). Therefore, when the assignment is made, the value of B 
is not substituted. However, the TYPE command displays MYFILE.DAT. This 
occurs because the command interpreter first substitutes the value &B for A. 
Next, it substitutesMYFILE.DAT for the symbol &B. If you were to redefine B, 
the result of the TYPE command would change accordingly. 

Observe the following rules: 

• Place the ampersand before, but not after, the symbol name. 

• An ampersand must follow a delimiter (any blank or special character). 

• You cannot use ampersands to request substitution within character strings 
enclosed in quotation marks (" "). 

• You cannot use ampersands to concatenate two or more symbol names. 

In general, do not use the ampersand for symbol substitution unless it is required 
to translate your symbols correctly. 

14.9.2 The Three Phases of Command Processing 

The command interpreter performs symbol substitution in three phases, as 
follows: 

• Phase 1 

Command input scanning (also called the lexical input phase) 

From left to right, the command interpreter evaluates symbols preceded 
by apostrophes. Symbols that are preceded by single apostrophes are 
translated iteratively, as described in Section 14.9.3.1. Symbols preceded 
by two apostrophes are not translated iteratively. 

• Phase 2 
Command parsing 

- The command interpreter analyzes the command line. It checks the first 
item on the line to see if it is a symbol. If it is, it is evaluated. 
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From left to right, the command interpreter evaluates symbols preceded 
by ampersands. 

Symbol substitution during this phase is not iterative. 

• Phase 3 
Expression evaluation 

- The command interpreter evaluates symbols that are preceded by the 
DEPOSIT, EXAMINE, IF, and WRITE commands. 

- The command interpreter evaluates symbols within lexical functions. 
Symbol substitution during this phase is not iterative. 

Note that the command interpreter does not scan any lines that are read as 
input data by commands or programs executed within a command procedure. 
Therefore, the command interpreter does not perform symbol substitution within 
these data lines. For example: 

$ RUN AVERAGE 

55 

57 

9999 

The program AVERAGE reads 55, 57, and 9999 from SYS$I NPUT (the command 
input stream). These data lines are never read by the command interpreter. If 
you enter symbol names as input, they are not evaluated. 

14.9.3 Repetitive and Iterative Substitution 

Symbol substitution can be repetitive or iterative: 

• Repetitive substitution results when more than one type of substitution 
occurs in a single command line. 

• Iterative substitution occurs when the command interpreter examines a 
substituted value to see if the value itself is a symbol. Iterative substitution 
occurs only when symbols preceded by apostrophes are translated during the 
first phase of command processing. 

The following sections describe iterative substitution. 

14.9.3.1 First Phase 

When you use an apostrophe ( ') to request symbol substitution, the command 
interpreter performs iterative substitution during the first phase of command 
processing. 

Substitution using apostrophes is not iterative, however, when a symbol is 
included in a quoted character string. For example: 

$ MAC = "5" 

$ A = ""MAC' " 

$ B = ""A'" 

$ SHOW SYMBOL B 

B = 5 Hex = 00000005 Octal = 00000000005 

After the statement B = ' A' the resulting value of the symbol B is 5. The 
explanation follows: 

• The symbol name A is enclosed in apostrophes, so it is replaced with its 
current value ('MAC' ). 

• Because this value (' MAC' ) is also enclosed in apostrophes, the command 
interpreter replaces MAC with its current value (5). 
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• Because this value (5) has no apostrophes, the first phase of command 
processing is complete. No further substitution is required during the second 
or third phases. Therefore, 5 is the final value given to the symbol name B. 

Note, however, what happens when you include A in a quoted character string: 

$ B = " " A' " 

$ SHOW SYMBOL B 
B = "'MAC'" 

In this case, B has the value ' MAC' . The symbol name A is replaced only once, 
because substitution is not iterative within quoted character strings. 

14.9.3.2 Second Phase 

The command interpreter performs iterative substitution automatically only 
when an apostrophe is in the command line. In some cases, you may want to nest 
command synonym definitions, as follows: 

$ MAC = "TYPE A.B" 

$ EXEC = "'MAC'" 

$ EXEC 

In this example, when EXEC is processed, the command interpreter performs 
substitution only once. The result is the string ' MAC' . The command interpreter 
displays an error message because it does not recognize MAC as a command. 

This error occurs because during the first phase of command processing, no 
substitution is performed (the string EXEC is not delimited by apostrophes). 
During the second phase, the string ' MAC' is substituted for EXEC because 
EXEC is the first value on the command line. This substitution is not iterative. 
Therefore, even though 'MAC' is delimited by apostrophes, no additional 
substitution is performed. 

To use the command synonym EXEC correctly, enclose it in apostrophes, as shown 
in this example: 

$ 'EXEC' 

In this case, the symbol EXEC is evaluated during the first phase of command 
processing. Because this substitution is iterative, (' MAC' ) is also evaluated and 
the string TYPE A.B is substituted. 

14.9.3.3 Third Phase 

When the command interpreter analyzes an expression in a command, any 
symbols specified in the expression are replaced only once. You can, however, 
force iterative substitution by using an apostrophe or an ampersand in the 
expression. When you force iteration in this way, you must remember the 
following: 

• The command interpreter performs all substitutions requested by apostrophes 
and ampersands before the command string is executed. 

• Commands that automatically perform symbol substitution do so after the 
first and second phases of command processing. 

The following example shows iterative substitution in an IF command: 

$ PI = "FRED.DAT" 

$ COUNT = 1 

$ IF P' COUNT' . EQS. "" THEN GOTO END 
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When the command interpreter scans this line, it replaces the symbol COUNT 
with its current value. The result is as follows: 

IF PI . EQS . "" THEN GOTO END 

Because this string has no apostrophes, the command interpreter does not 
perform any more substitution. However, when the IF command executes, it 
automatically evaluates the symbol name PI and replaces it with its current 
value. 

Note, however, that if substitution does not result in a valid symbol name, the 
command fails. For example: 

$ FILENAME = "A.B" 

$ IF 'FILENAME' .NES. "" THEN TYPE 'FILENAME' 

The command interpreter replaces the symbol FILENAME with its current value 
(A.B). The result is as follows: 

IF A.B .NES. "" THEN TYPE A.B 

When the IF command executes the command line, A.B is not a valid symbol 
and an error occurs. For this IF command to be processed correctly, omit the 
apostrophes, as follows: 

$ IF FILENAME .NES. "" THEN TYPE 'FILENAME' 

14.9.4 Undefined Symbols 

If a symbol is not defined when it is used in a command line, the command 
interpreter either displays an error message or replaces the symbol with a null 
string, depending on the context. The rules are as follows: 

• During the first and second phases of command processing, the command 
interpreter replaces all undefined symbols that are preceded by apostrophes 
or ampersands with null strings. 

• During the third phase of command processing, if the command interpreter 
finds an undefined symbol, it displays a warning message and does not finish 
processing. 

The following example shows how the command interpreter processes an 
undefined symbol that is preceded by an apostrophe: 

$ FILE := MYFILE' FILE_TYPE' 

$ SHOW SYMBOL FILE 
FILE = "MYFILE" 

$ PRINT 'FILE' 

When the symbol FILE is created, the symbol FILE_TYPE is replaced with its 
current value. If FILE_TYPE is not defined, the command interpreter replaces 
FI LE_TYPE with a null string. The absence of a file type in the file specification 
causes the PRI NT command to use the default file type .LIS. Thus, the file 
specification is interpreted as MYFILE. LIS. 

In the following example, the expression is evaluated during the third phase of 
command processing: 

$ A = 1 
$ C = A + B 

%DCL-W-UNDSYM, undefined symbol - check validity and spelling 

The symbol B is undefined, so the command interpreter cannot evaluate the 
expression. 
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Command Procedures: Programming with DCL 


A command procedure is a file that contains DCL commands and data lines used 
by DCL commands. You can write both simple and complex command procedures. 
A simple command procedure executes a series of DCL commands in the order in 
which they are written. For example, the following command procedure sets your 
default directory and examines it: 

$ ! PROCEDURES.COM 

S ! 

$ ! Enter [MAINT. PROCEDURES] and examine it 
$ SET DEFAULT [MAINT . PROCEDURES] 

$ DIRECTORY 

A complex command procedure performs program-like functions. For example, 
the following command procedure asks for directory names and examines the 
directories: 

$ ! DIRECTORY.COM 

S ! 

$ ! Examine directories 
$START : 

$ INQUIRE DIR_NAME "Directory name" 

$ IF DIR_NAME . EQS . "" THEN GOTO END 
$ DIRECTORY ' DIR_NAME' 

$ GOTO START 
$END : 

This chapter describes how to write and use command procedures. A sample 
login command procedure is included at the end of the chapter. Appendix C 
includes annotated command procedures. 

15.1 Executing a Command Procedure 

You can execute command procedures in the following ways: 

• I nteractively from DCL level 

• I n batch mode 

• From within another command procedure 

• On a remote node 

• At a DCL command line 

The following sections describe each of these methods, as well as how to terminate 
a command procedure while it is executing. 
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15.1.1 Executing a Command Procedure Interactively 

To execute a command procedure interactively, enter an at sign (@) followed by 
the file specification of the command procedure. The default file type is .COM . 
For example, the following command executes the procedure SETD.COM in the 
[MAI NT.PROCEDURES] directory on the WORKDISK disk: 

$ 0WORKDISK: [MAINT. PROCEDURES] SETD [Return] 

You can also define a global symbol or a logical name to represent this command 
line. For example, to use a symbol to execute the command procedure shown 
in the preceding example, include the following line in your login command 
procedure: 

$ SETD == "0WORKDISK: [MAINT. PROCEDURES] SETD" 

Then, to execute the procedure SETD.COM , enter the symbol name: 

$ SETD | Return | 

By default, when you execute a command procedure interactively, it displays 
output at your terminal. Flowever, you can redirect output to a file by using the 
/OUTPUT qualifier. I n the following example, output from SETD.COM is written 
to the file RESULTS.TXT instead of to the terminal: 

$ @SETD/OUTPUT=RESULTS . TXT 


Note 

When you use the /OUTPUT qualifier, be sure to place it immediately 
after the command procedure file name, with no intervening spaces. 
Otherwise DCL interprets the qualifier as a parameter to be passed to the 
procedure. 


When you redirect command procedure output to a file, the procedure sends 
error messages to the terminal as well as to the file receiving the output. See 
Section 15.4.2.4 for more information on controlling error messages. 

15.1.2 Executing a Command Procedure as a Batch Job 

If you use command procedures that require lengthy processing time (for example, 
to compile or assemble large programs), submit these procedures as batch jobs so 
you can continue to use your terminal interactively. 

If your system is part of a network, you can submit a command procedure to 
execute as a batch job on a remote node. Within a command procedure, you can 
use DCL commands to open and close files on a remote node and read and write 
records in these files, using the same commands and qualifiers as for local files. 

You can also determine whether and how a command procedure is restarted 
after a system failure. Section 15.7.2 explains how to label the point at which 
a command procedure should restart if the system fails. Chapter 17 describes 
how to submit a batch job with the DCL command SUBMIT. To specify that the 
job should be restarted after a system failure, include the SUBMIT command 
qualifier /RESTART. 
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15.1.3 Executing a Command Procedure on a Private Disk Volume 

When you submit a command procedure with the SUBMIT command, you cannot 
access files on allocated devices. You can submit a command procedure that 
is located on a private disk volume if you mount the volume with the /SHARE 
qualifier. To submit a command procedure on a magnetic tape volume, you first 
must copy the command procedure to a shared disk volume and then submit the 
command procedure on the disk. 

You can execute a command procedure that resides on a tape volume as long as 
the procedure does not invoke other procedures and does not issue any GOTO 
commands that refer to labels in the procedure preceding the GOTO command. 

I n this case, copy the command procedure from the magnetic tape volume to a 
local disk, from which you can then invoke the command procedure. 

15.1.4 Changing Command Levels 

A command level is an input stream for the DCL command interpreter. When 
you log in and enter commands at your terminal, you are entering commands 
from command level 0. A simple interactive command procedure executes at 
command level 1. When the procedure terminates and the DCL prompt reappears 
on your screen, you are back at command level 0. 

There are two ways to create new command levels: 

• Nest command procedures by using an execute procedure (@) command 
inside one command procedure to invoke another command procedure. 

• Use the CALL command to call a subroutine that exists within the command 
procedure. 

Each time you nest a command procedure or use the CALL command, the 
command level increases by 1. You can create a maximum of 32 command levels. 

To execute a command procedure from within another command procedure, use 
the execute procedure ( @) command followed by the file specification of the 
procedure. For example, the following command procedure WRITEDATE.COM 
invokes the command procedure GETDATE.COM : 

$ ! WRITEDATE.COM 

$ INQUIRE TIME "What is the current time in hh:mm format?" 

$ 0GETDATE [JONES . COM] GETDATE . COM 

The following command procedure uses both the CALL command and the execute 
procedure ( @) command to create the indicated command levels when you execute 
it interactively: 
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$ ! Example of command levels 
$ WRITE SYS$OUTPUT "This is an example" 1 

$ 0EXAMPLE 2 

$ DEFINE FRIEND CAROL 3 

$ ON WARNING THEN EXIT 

$ CALL SUB1 4 

$ DEASSIGN FRIEND 
$ EXIT 
$ SUB1 : 

$ SUBROUTINE 


$ CALL SUB2 5 

$ EXIT 6 

$ ENDSUBROUTINE 
$ SUB2 : 

$ SUBROUTINE 


$ EXIT 7 

$ ENDSUBROUTINE 
$ EXIT 

The following actions occur when this command procedure is executed: 

1 The command procedure begins executing at command level 1. 

2 The nested command procedure EXAMPLE.COM executes at command level 
2 . 

3 After EXAMPLE.COM finishes executing, the DEFINE command executes at 
command level 1. 

4 The CALL SUB1 command creates a new command level; subroutine SUB1 
executes at command level 2. 

5 The CALL SUB2 command within subroutine SUB1 creates a new command 
level. Subroutine SUB2 executes at command level 3. 

6 The EXIT command within SUB1 returns control to the DEASSI GN command 
following the CALL SUB1 command. The DEASSIGN command executes at 
command level 1. 

7 The EXIT command within SUB2 returns control to subroutine SUB 1 which 
is executing at command level 2. Note that this command executes before the 
previously described command. 

In a batch job, command level 0 is defined as the command procedure that is 
submitted for batch execution. If the batch job contains an execute procedure ( @) 
command, the commands in the nested procedure are executed at command level 
1. I n batch jobs, as in interactive mode, you can create up to 32 command levels. 

By convention, DCL level (command level 0) is the highest command level 
and command level 31 is the lowest command level. Thus, when you move from 
command level 3 to command level 2, you are moving to the next higher command 
level. 
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15.1.5 Executing a Command Procedure on a Remote Node 

You can execute a command procedure in the top-level directory of another 
account on a remote node by using the TYPE command. The TYPE command lets 
you execute command procedures to do the following: 

• Display the status of services in the local VMScluster that are not provided 
clusterwide. 

• List the users logged in to a remote node. 

For example, the following command procedure, SHOWUSERS.COM, displays 
the users logged in to the remote node on which the command procedure 
resides: 

$ ! SHOWUSERS.COM 
$! 

$ IF F$MODE() .EQS . "NETWORK" THEN DEFINE/USER SYS$OUTPUT SYS$NET 
$ SHOW USERS 

To execute a command procedure remotely, use an access control string in the 
TYPE command line, as follows: 

TYPE node_name"user_name password"::"TASK=command_procedure" 

The variables user_name and password are the user name and password for 
the account on the remote node. For example, if the command procedure 
SHOWUSERS.COM is located in the top-level directory of the Bl RD account 
on node ORIOLE and the password is BOULDER, you can execute the procedure 
by enteri ng the fol I owi ng command I i ne: 


$ TYPE ORIOLE"BIRD BOULDER" :: "TASK=SHOWUSERS" 



OpenVMS User 

Processes at 11 

-DEC-1994 17 

: 20 : 13 . 

Total 

number of users 

= 4, number of 

processes = 

4 

Username 

Node 

Interactive 

Subprocess 

Batch 

FLICKER 

AUTOMA 

2 

1 


ROBIN 

FABLES 

1 

2 

1 

DOVE 

MURMUR 

1 



DUCK 

FABLES 

1 

1 



Note 

Your password will be visible on your terminal when you use this 
command line. Take the appropriate security precautions as described in 
Chapter 2. 


SHOWUSERS.COM executes the DCL command SHOW USERS on the remote 
nodeORIOLE. The TYPE command displays the output from SHOWUSERS.COM 
on the local node; that is, on the terminal from which you enter the TYPE 
command. 

15.1.6 Executing a Command Procedure Within a DCL Command Line 

You can create a command procedure that specifies parameters or qualifiers only, 
then use the command procedure within a DCL command string. This type of 
command procedure is useful when there is a set of parameters or qualifiers 
that you use frequently with one or more commands. To execute the command 
procedure, use the execute procedure ( @) command in the command string where 
you would normally use the qualifiers or parameters. 
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For example, suppose you frequently use the same set of qualifiers when you 
enter the LINK command. You could create a command procedure that contains 
the following qualifiers: 

$!This command procedure contains command qualifiers 
$ ! for the LINK command 
$! 

/DEBUG/ SYMBOL_TABLE/MAP/FULL/CROSS_REFERENCE 

To use this command procedure, execute it on the command line where you would 
otherwise place the qualifiers. For example, if you name the command procedure 
DEFLINK.COM, you would use the following command line to link an object 
module named SYNAPSE. OBJ by using the qualifiers that you specified in the 
command procedure: 

$ LINK SYNAPSE0DEFLINK 

Note that you cannot include a space before the at sign ( @) character when the 
command procedure begins with a qualifier name. 

The next example shows a command procedure named PARAM.COM that 
contains parameters: 

$!This command procedure contains parameters 
$!for the LINK command 
$! 

CHAP1 , CHAP 2 

To execute the procedure, use it in a command string in place of a parameter 
name. For example: 

$ DIRECTORY 0PARAM 

Note that you must precede the at sign ( @) character with a space when the 
command procedure begins with a parameter. 

15.2 Exiting from a Command Procedure 

A command procedure exits when it reaches the end of the procedure, an EXIT 
command, or a STOP command. If the exit is caused by the end of the procedure 
or an EXIT command, control returns to the next higher command level. If the 
exit is caused by the EXIT command, you can return a status value to the next 
higher command level by specifying the value as the parameter of the EXIT 
command. For example, if you invoke SUB at DCL command level and SUB calls 
SUB1, the following sequence of actions occurs: 

1. Exiting from SUB1 returns you to SUB at the command line following the 
call toSUBl. 

2. Exiting from SUB returns you to DCL command level. 

If the exit is caused by the STOP command, control always returns to DCL 
command level (command level 0), regardless of the command level in which the 
STOP command executes. If you execute the STOP command in a batch job, the 
batch job terminates. 

You can interrupt a command procedure by pressing Ctrl/Y and then using the 
EXIT command or the STOP command to terminate the procedure. I n this case, 
both commands return you to command level 0. For example: 
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$ @TESTALL [Return] 

| Ctrl/Y | 

$ EXIT [Return] 

S 

In the preceding example, you interrupt the procedure TESTA LL by pressing 
Ctrl/Y. The EXIT command terminates processing of the procedure and restores 
command level 0. Note that you can also enter the STOP command after you 
interrupt the procedure. For more information on using the EXIT and STOP 
commands, refer to Section 15.6.7 and Section 15.6.8, respectively. 

Note 

When you interrupt a command procedure, if the command (or image) 
that you interrupt declares any exit-handling routines, the EXIT 
command gives these routines control. However, the STOP command does 
not execute these routines. 


15.3 Formatting a Command Procedure 

Use a text editor (or the DCL command CREATE) to create and format a 

command procedure according to the following rules: 

• Use a dollar sign ( $) to begin each line containing a command, comment, or 
label. Command lines that do not begin with a dollar sign might be correctly 
interpreted by DCL, but Digital strongly recommends that any DCL command 
line start with a dollar sign. 

• To begin a line containing data, omit the dollar sign. (If you need to include 
a data line that begins with a dollar sign ($), use the DCL commands DECK 
and EOD, as described in Section 15.4.1.3.) 

• Use comments at the beginning of a procedure to describe the procedure 
and the parameters passed to it; place them at the beginning of each block of 
commands to describe that section of the procedure. Use an exclamation point 
(!) to indicate the beginning of a comment; the command interpreter ignores 
all text to the right of an exclamation point when the command procedure 
executes. To include a literal exclamation point in a command line, precede 
and follow it with quotation marks ( " " ). 

• Use complete names for commands and qualifiers. 

• Put labels on separate lines to make loops, subroutines, and conditional code 
easier to understand. The GOTO, GOSUB, and CALL commands transfer 
control to labels, which mark the beginning of a loop, a section of code, or a 
subroutine. 

• Use label names that contain fewer than 255 characters and no blank spaces. 

• Differentiate labels from commands by placing labels immediately after the 
dollar sign ( $) and by preceding commands with spaces. 

• End labels with a colon. 

• Separate command sequences with lines containing both a dollar sign and 
an exclamation point ( $! ). This makes it easier to see the outline of the 
command procedure. If you insert blank lines, the command interpreter 
interprets them as data lines and produces a message warning you that the 
data lines were ignored. 
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• Use continuation lines to make a procedure easier to read. Note that 
continuation lines do not begin with dollar signs. For example: 

S PRINT LAB. DAT 

/AFTER=17 : 00 - 
/COPIES=20 
/ NAME = " C OMGU I DE " 

In addition, if you use the .COM file type when you name the command 
procedure, you can execute the procedure by specifying the file name only. The 
SUBMIT and execute procedure (@) commands assume the file type is .COM, 
unless you specify otherwise. 

15.4 Performing Command Procedure input/Output (I/O) 

You can obtain input for command procedures from within the command 
procedure itself, interactively (from a terminal), or from a separate file. You can 
direct the output (data, error messages, and verification of command lines) from 
a command procedure to your terminal or to another file. The following sections 
describe different ways to obtain input for, and redirect output from, a command 
procedure. 

15.4.1 Passing Data to Command Procedures 

Command procedures frequently require data provided by a user. To use the 
same data each time a command procedure executes, place the data on data lines 
following the command that requires input. For example, the following command 
procedureexecutestheimageCENSUS.EXE, which reads the data 1992, 1993, 
and 1994 each time the procedure executes: 

$ ! CENSUS.COM 
$ ! 

$ RUN CENSUS 

1992 

1993 

1994 

$ EXIT 

DCL passes the text on a data line directly to the image; it does not process 
symbols, logical names, or arithmetic expressions in the data lines. 

To specify different data each time a command procedure executes, use one of the 
following methods: 

• Pass the data as one or more parameter values. 

• Use the I NQU I RE or READ command within the command procedure to 
prompt for data. 

• Specify a device or file from which to read the data by redefining the logical 
name SYS$INPUT. 

The following sections describe each of these methods. 

15.4.1.1 Using Parameters to Pass Data 

When you invoke a command procedure, you can pass up to eight parameters to 
it. Place the parameters after the file specification of the command procedure, 
and separate the parameters with one or more spaces or tabs. For example, 
the following command invokesSUM.COM and passes eight parameters to the 
procedure: 

$ @SUM 34 52 664 89 2 7 87 3 
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DCL places parameters passed to a command procedure in the local symbols 
PI to P8: PI is assigned the first parameter value; P2 the second; P3 the third; 
and so on. If you pass fewer than eight values, the extra symbols are assigned 
null values. A null value is a string with no characters and is represented by 
quotation marks ( " "). 

Specify a parameter value as one of the following: 

• I nteger 

When you specify an integer, it is converted to a string. In the following 
example, PI is the string value 24; P2 is the string value 25. 

$ @ ADDER 24 25 

You can, however, use the symbols PI and P2 in both integer and character 
string expressions; DCL performs the necessary conversions automatically. 

• Character string 

To preserve spaces, tabs, or lowercase characters in a character string, place 
quotation marks before and after the string. For example: 

$ 0DATA "Paul Cramer" 

I n this example, PI is Paul Cramer and P2 is null. If you omit the quotation 
marks, each character string is passed as a separate parameter. For example: 

$ 0DATA Paul Cramer 

In this example, the strings Paul and Cramer are converted to uppercase 
letters; PI is PAUL and P2 is CRAMER. 

As another example, if you invoke DATA.COM with the following command: 

$ 0DATA "Paul Cramer" 24 "(555) 111-1111" 

PI to P8 are defined in DATA.COM as follows: 

PI = Paul Cramer 
P2 = 24 

P3 = (555) 111-1111 
P4-P8 = null 

• Symbol 

To pass the value of a symbol, place an apostrophe before and after the 
symbol, as shown in the foil owing example. 

$ NAME = "Paul Cramer" 

$ 0DATA 'NAME' 

I n this example, PI is Paul and P2 is Cramer. 

DCL removes quotation marks when you pass a symbol to a command 
procedure. To preserve spaces, tabs, and lowercase characters in the symbol 
value, enclose the value in three sets of quotation marks. You must also use 
three sets of quotation marks to include a quotation mark as part of a string. 
For example: 

$ NEW_NAME = Paul Cramer 

$ 0DATA ' NEW_NAME ' 

I n this example, PI is "Paul Cramer" and P2 is null. 
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An alternative is to enclose the text in quotation marks and where a symbol 
appears, precede the symbol with two apostrophes, and follow it with one 
apostrophe as follows: 

$ ! DATA.COM 
$ 0NAME ""PI'" 

• Null 

To pass a null parameter, use one set of quotation marks as a placeholder in 
the command string. I n the following example, the first parameter passed to 
DATA.COM is a null parameter: 

$ 0DATA "" "Paul Cramer" 

I n this example, PI is null and P2 is Paul Cramer. 

Passing Parameters to a Nested Command Procedure 

You can pass up to eight parameters to a nested command procedure. The local 
symbols PI to P8 in the nested procedure are not related to the local symbols PI 
to P8 in the invoking procedure. In the following example, DATA.COM invokes 
the nested command procedure NAME.COM: 

$ ! DATA.COM 
$ 0NAME 'PI' Joe Cooper 

If PI in DATA.COM is the string Paul Cramer, which contains no quotation 
marks, itispassedtoNAME.COM as two parameters. In NAME.COM, PI to P8 
are defined as follows: 

PI = PAU L 
P2 = CRAMER 
P3 =J OE 
P4 = COOPER 
P5-P8 = null 

If PI in DATA.COM is "Paul Cramer" (quotation marks included), you can pass 
the value to NAME.COM as one parameter by enclosing PI in three sets of 
quotation marks, as follows: 

$ ! DATA.COM 
$ QUOTE = """ 

$ PI = QUOTE + PI + QUOTE 
$ 0NAME 'PI' "Joe Cooper" 

In this example, PI is Paul Cramer and P2 is J oe Cooper in the command 
procedure NAME.COM . 

Passing Parameters to a Batch Job 

To pass parameters to a command procedure executed in batch mode, use 
the SUBMIT command qualifier /PARAMETERS. For example, the following 
command passes three parameters to the command procedures ASK.COM and 
GO.COM , which are executed as batch jobs: 

$ SUBMIT/PARAMETERS= (TODAY, TOMORROW, YESTERDAY) ASK.COM, GO.COM 

Note 

You can also pass data to a batch job by including the data in a command 
procedure or by defining SYS$I NPUT to be a file (see Section 15.4.1.3). 
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The specified parameters are used for each command procedure in the 
batch job. 


If you execute more than one command procedure using a single SUBMIT 
command, the specified parameters are used for each command procedure in the 
batch job. For example, the following SUBMIT command passes two parameters 
to the command procedures LIBRARY.COM and SORT.COM: 

$ SUBMIT- 

_$ /PARAMETERS= (DISK: [ACCOUNT . BILLS] DATA. DAT, DISK: [ACCOUNT ] NAME . DAT ) - 
_$ LIBRARY.COM, SORT.COM 

Your batch job executes as if you had logged in and executed each of the command 
procedures. For example, the previous SUBMIT command executes a batch job 
that logs in under your account, executes your login command procedure, and 
then executes the following commands: 

$ @ LIBRARY DISK: [ACCOUNT.BILLSJDATA.DAT DISK: [ACCOUNT] NAME . DAT 
$ 0SORT DISK: [ACC0UNT.BILLS1DATA.DAT DISK : [ACCOUNT] NAME .DAT 

15.4.1.2 Prompting for User Input 

You can use the I NQUI RE and READ commands to obtain data for command 
procedures interactively. Both commands prompt for input and assign the 
response to a symbol. Flowever, the commands differ in the way they request 
and interpret the response, as follows: 

• The I NQUI RE command prompts for a value, reads the value from the 
terminal, and assigns it to a symbol. For example, the following command 
issues the prompt Filename: to your terminal and assigns your response to 
the symbol FILE: 

$ INQUIRE FILE "Filename" 

By default, the I NQUI RE command converts the response to uppercase, 
replaces multiple blanks and tabs with a single space, and removes leading 
and trailing spaces. In addition, if the response includes symbols or lexical 
functions, the INQUIRE command performs apostrophe substitution (see 
Chapter 14). 

To preserve lowercase characters, multiple spaces, and tabs, enclose your 
response in quotation marks ( " " ). To include quotation marks in your 
response, use two sets of quotation marks ( "" "" ) in the places you want 
quotation marks to appear. The following example shows how to include an 
access control string by enclosing the user name and password in two sets of 
quotation marks: 

$ INQUIRE FILE "Filename" 

Filename: "0Z""WITCH GLINDA" ":: [GLINDA] SPELLS .DAT" 

$ SHOW SYMBOL FILE 

FILE = "0Z"WITCH GLINDA" :: [GLINDA] SPELLS . DAT" 

• The READ command prompts for a value, reads the value from the source 
specified by the first parameter, and assigns it to the symbol named as the 
second parameter. For example, the following command issues the prompt 
Filename: to your terminal, reads the response from the source specified by 
the logical name SYS$COMM AND (by default, the terminal), and assigns the 
response to the symbol FILE: 

$ READ/PROMPT="Filename: " SYS $ COMMAND FILE 
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If you omit the /PROMPT qualifier, the READ command displays Data: as 
the default prompt. 

The READ command accepts all characters typed on the terminal in response 
to the prompt as an exact character string value (case, spaces, and tabs are 
preserved). 

You can also write command procedures that can either accept parameters or 
prompt for user input if the required parameters are not specified. For example: 

$ ! Prompt for a file name if name 

$ ! is not passed as a parameter 

$ IF PI . EQS. "" THEN INQUIRE PI "Filename" 

$ COPY 'PI' DISK5: [RESERVED]*.* 

$ EXIT 


Note 

If you submit a command procedure for execution as a batch job, DCL 
reads the value for a symbol specified in an INQUIRE command from the 
data line following the I NQU I RE command. I f you do not i ncl ude a data 
line, the symbol is assigned a null value. 


15.4.1.3 Obtaining Data from SYS$INPUT 

Commands, utilities, and other system images get their input from the source 
specified by the logical name SYS$I N PUT, which is the default input stream. In 
a command procedure, SYS$INPUT is defined as the command procedure file; 
commands or images that require data look for data lines in the file. However, 
by redefining SYS$INPUT, you can provide data from your terminal or from a 
separate input file. 

Using Your Terminal 

To enable an image called from a command procedure to obtain input 
interactively, rather than from the data lines in the command procedure, redefine 
SYS$INPUT to be your terminal. 

For example, the following command procedure allows you to provide input 
interactively to the image CENSUS.EXE : 

$ ! Execute CENSUS getting data from the terminal 
$ DEFINE/USER_MODE SYS$INPUT SYS$COMMAND 
$ RUN CENSUS 
$ EXIT 

The DE FI N E/USE R_M ODE command temporarily redefines SYS$INPUT while 
CENSUS.EXE is running, so CENSUS.EXE obtains its input from the terminal. 
AfterCENSUS.EXE completes, SYS$INPUT reverts to its original definition (the 
command procedure file). 

To use a DCL command or utility that requires interactive input in a command 
procedure, you must redefine SYS$I NPUT to be your terminal. For example, the 
following command procedure uses EVE as the text editor: 
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$ ! Obtain a list of your files 
$ DIRECTORY 
$ ! 

$ ! Get file name and invoke the EVE editor 
$ EDIT_L00P : 

$ INQUIRE FILE "File to edit (Press Return to end) " 

$ IF FILE .EQS. "" THEN EXIT 

$ DEFINE/USER_MODE SYS$INPUT SYS$ COMMAND 

$ EDIT/TPU 'FILE' 

$ GOTO EDIT_LOOP 

This command procedure prompts for file names until you terminate the loop by 
pressing the Return key. When you enter a file name, the procedure automatically 
invokes EVE to edit the file. While the editor is running, SYS$I NPUT is defined 
as the terminal so you can enter your edits interactively. 

Using a Separate File 

A command procedure can get input from a file by defining SYS$INPUT as a file. 
For example, the following command procedure defines SYS$I NPUT as the file 
YEARS.DAT and then invokes the program CENSUS. CENSUS reads its input 
from the file YEARS.DAT. 

$ ! CENSUS.COM 

S ! 

$ ! Execute CENSUS 

$ DEFINE/USER_MODE SYS$INPUT YEARS.DAT 
$ RUN CENSUS 

Note that the command procedure passes the text on a data line directly to the 
command or image. DCL does not process the data lines. If you include DCL 
symbols or expressions on data lines, DCL will not substitute values for the 
symbols or evaluate the expressions. If you use an exclamation point (!) in a data 
line, the image to which you pass the data processes the exclamation point. 

To include data lines that begin with dollar signs, use the DECK and EOD 
(end-of-deck) commands. For example: 

$ ! Everything between the commands DECK and EOD 
$ ! is written to the file WEATHER.COM 

S ! 

$ CREATE WEATHER.COM 
$ DECK 

$ FORTRAN SUMMER 
$ LINK SUMMER 
$ RUN SUMMER 
$ EOD 
$ ! 

$ ! Now execute WEATHER.COM 
$ @ WEATHER 
$ EXIT 

You can also place programs in the command procedure file by specifying the 
name of the data file as SYS$INPUT. This causes the compiler to read the 
program from the command procedure rather than from another file. The 
following example illustrates a command procedure that contains a FORTRAN 
command followed by the program's statements: 
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$ FORTRAN/OBJECT=TESTER/LIST=TESTER SYS$INPUT 
C THIS IS A TEST PROGRAM 
A = 1 
B = 2 
STOP 
END 

$ PRINT TESTER. LIS 
$ EXIT 

In this example, the FORTRAN command uses the logical name SYS$I N PUT 
to identify the file to be compiled. Because SYS$I N PUT is equated to the 
command procedure, the FORTRAN compiler compiles the statements following 
the FORTRAN command (up to the next line that begins with a dollar sign). 
When the compilation completes, two output files are created: TESTER. OBJ and 
TESTER. LIS. The PRINT command then prints the file. 


15.4.2 Directing Output from Command Procedures 

Command procedures can direct output in the following ways: 


• Writing data to a terminal 

• Redirecting output from commands and images 

• Returning data from a command procedure 

• Redirecting error messages 

• Verifying command procedure execution 

The following sections describe how to use each of these methods. 


15.4.2.1 Writing Data to a Terminal 


To write data to a terminal, you can use the WRITE command or the TYPE 
command. 

Use the WRITE command to write data that contains symbols or lexical functions. 
Unless you enclose the data in quotation marks (" "), the WRITE command 
performs symbol substitution automatically. Table 15-1 shows how to use the 
WRITE command with different types of data. 


Table 15-1 Uses for the WRITE command 


Example 


Explanation 


Character String 


To display a character string as 
literal text, enclose the string in 
quotation marks (" "). 


$ WRITE SYS$OUTPUT "Two files are written. 
Two files are written. 


Quotation Marks in a Character String 

$ WRITE SYS$OUTPUT "Summary of ""Q & A"" Session 
Summary of "Q & A" Session 


To include quotation marks in a 
character string, use two sets of 
quotation marks ( " " " "). 


(continued on next page) 
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Table 15-1 (Cont.) Uses for the WRITE command 


Example 

Explanation 

Concatenating Character Strings 

$ WRITE SYS$OUTPUT "Report by Mary Jones" + - 
" Prepared April 15, 1994" 

Report by Mary Jones Prepared April 15, 1994 

To continue a line of text on more 
than one line, concatenate the two 
strings with a plus sign ( +) and a 
hyphen (-). (For more information 
on continuing a character string 
over two lines, see Chapter 14.) 

Symbols 

$ FILE = "STAT1.DAT" 

$ WRITE SYS$OUTPUT FILE 

STAT1.DAT 

The WRITE command performs 
symbol substitution automatically 
and displays the value 
(STAT1.DAT) of the symbol (FILE). 

Symbols in a Character String 

$ AFILE = "STAT1.DAT" 

$ BFILE = "STAT2.DAT" 

$ WRITE SYS$OUTPUT "''AFILE' and "BFILE' ready." 
STAT1.DAT and STAT2.DAT ready. 

To force symbol substitution 
within a character string, use 
the apostrophe ('). (For more 
information on how to combine 
character strings and symbols in 
expressions, see Chapter 14.) In 
this example, STAT1.DAT is the 
translation of the symbol AFILE; 
STAT2.DAT is the translation of 
the symbol BFILE. 


Use the TYPE command to display text that is several lines long and does not 
require symbol substitution. TheTYPE command writes data from the file you 
specify to SYS$OUTPUT. If you specify SYS$I NPUT as the input file, the TYPE 
command reads data from the data lines that follow and displays the lines on the 
terminal. For example: 

$ ! Using TYPE to display lines 
$ TYPE SYS$INPUT 
REPORT BY MARY JONES 
PREPARED APRIL 15, 1995 

SUBJECT: Analysis of Tax Deductions for 1994 


S EXIT 

You can also use the TYPE command to execute command procedures on a remote 
node (see Section 15.1.5). 

15.4.2.2 Redirecting Output from Commands and Images 

Commands, utilities, and other system images write their output to the source 
specified by the logical name SYS$OUTPUT. By default, SYS$OUTPUT is 
equated to the terminal. However, you can redirect the output to a file in one 
of the following ways: 

• Use the /OUTPUT qualifier when you invoke the command. DCL commands 
that accept the /OUTPUT qualifier include: ACCOUNTING, CALL, 
DIRECTORY, HELP, LIBRARY, RUN (process), SPAWN, and TYPE. 


15-15 


Command Procedures: Programming with DCL 
15.4 Performing Command Procedure Input/Output (I/O) 


• Temporarily redefine SYS$OUTPUT as a file. For example, the following 
command procedure redirects the output from the SHOW USERS command 
to a file: 

S DEFINE /USER_M0DE SYS$OUTPUT SHOW_USER.DAT 
$ SHOW USERS 
$ ! 

$ ! Process the information in SHOW_USER.DAT 
S OPEN/READ INFILE SHOW_USER.DAT 
S READ INFILE RECORD 


$ CLOSE INFILE 


$ EXIT 


The /USE R_M ODE qualifier creates a temporary logical name assignment 
that is in effect only until the next image completes. The new definition 
for SYS$OUTPUT is in effect only for the execution of the SHOW USERS 
command. After the command executes, SYS$OUTPUT reverts to the default 
definition (the terminal). 

To suppress output from a command, temporarily define SYS$OUTPUT as a null 

device. For example: 

$ DEFINE/USER_MODE SYS$OUTPUT NL: 

$ APPEND NEW_DATA.DAT STATS.DAT 


You cannot use the DEFI N E/USE R_M ODE command to redirect output from 
DCL commands that are executed within the command interpreter. Table 15-2 
shows a complete list of DCL commands that are performed within the command 
interpreter, instead, use the DEFINE command to redefine SYS$OUTPUT and 
use the DEASSI GN command to delete the definition when you are through with 
it. For example, to redirect output from the SHOW Tl ME command to the file 
TIME.DAT, enter the following commands: 

$ DEFINE SYS$OUTPUT TIME.DAT 
$ SHOW TIME 
$ DEASSIGN SYS$OUTPUT 

After you deassign SYS$OUTPUT, it reverts to the default definition (the 
terminal). For more information on redefining SYS$OUTPUT, see Chapter 13. 

Table 15-2 Commands Performed Within the Command Interpreter 


ATTACH 

CLOSE 


ALLOCATE 

CALL 

CONNECT 


ASSIGN 
CANCEL 
CONTINUE 
DEASSIGN 
DEFINE 
DISCONNECT 
ENDSUBROUTINE 
(continued on next page) 


CREATE/LOGI CAL_NAM E_TABLE DEALLOCATE 


DEBUG 

DEFINE/KEY 

ELSE 


DECK 

DELETE/SYMBOL 

ENDIF 
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Table 15-2 (Cont.) Commands Performed Within the Command Interpreter 


EOD 

EXAMINE 

EXIT 

GOSUB 

GOTO 

IF 

INQUIRE 

ON 

OPEN 

READ 

RECALL 

RETURN 

SET CONTROL 

SET DEFAULT 

SET KEY 

SET ON 

SET OUTPUT_RATE 

SET PROMPT 

SET PROTECTION/DEFAULT 

SET SYMBOL/SCOPE 

SET UIC 

SET VERIFY 

SHOW DEFAULT 

SHOW KEY 

SHOW PROTECTION 

SHOW QUOTA 

SHOW STATUS 

SHOW SYMBOL 

SHOW TIME 

SHOW TRANSLATION 

SPAWN 

STOP 

SUBROUTINE 

THEN 

WAIT 

WRITE 


15.4.2.3 Returning Data from a Command Procedure 

Global symbols and logical names return data from a command procedure to a 
calling procedure or to DCL command level. You can read a global symbol or a 
logical name at any command level. 

The following command procedure shows how to pass a value with a global 
symbol created with a global assignment statement: 

$ 0DATA "Paul Cramer" 

$ ! DATA.COM 
$ ! 

$ ! PI is a full name. 

$ ! NAME.COM returns the last name in the 
$ ! global symbol LAST_NAME . 

S ! 

$ 0NAME 'PI' 

$ ! NAME.COM 
$ ! PI is a first name 
$ ! P2 is a last name 

$ ! return P2 in the global symbol LAST_NAME 
$ LAST_NAME == P2 
$ EXIT 

$ ! write LAST_NAME to the terminal 
$ WRITE SYS$0UTPUT "LAST_NAME = ' ' LAST_NAME' " 

LAST_NAME = CRAMER 

I n this example, DATA.COM invokes the command procedureNAME.COM, 
passingNAME.COM a full name. NAME.COM places the last name in the global 
symbol LAST_NAME. When NAME.COM completes, DCL continues executing 
DATA.COM, which reads the last name by specifying the global symbol LAST_ 
NAME.ThecommandprocedureNAME.COM would be in a separate file. It is 
shown indented in the previous example for clarity. 

Logical names can return data from a nested command procedure to the calling 
procedure. For example, the following command procedure, REPORT.COM, 
obtains the file name for a report, equates the file name to the logical name 
REPORT_FI LE, and executes a program that writes a report to REPORT_FI LE: 
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$ ! Obtain the name of a file and then run 
$! REPORT.EXE to write a report to the file 
$! 

$ INQUIRE FILE "Name of report file" 

$ DEFINE/NOLOG REPORT_FILE 'FILE' 

$ RUN REPORT 
$ EXIT 

If you invoke REPORT.COM from another procedure, the calling procedure can 
use the logical name REPORT_FILE to refer to the report file. For example: 

$ ! Command procedure that updates data files 
$! and optionally prepares reports 
$! 

$ UPDATE: 


$ INQUIRE REPORT "Prepare a report [Y or N] " 

$ IF REPORT THEN GOTO REPORT_SEC 
$ EXIT 
$! 

$ REPORT_SEC : 

$ @ REPORT 

$ WRITE SYS$OUTPUT "Report written to ", F$TRNLNM("REPORT_FILE") 

$ EXIT 

15.4.2.4 Redirecting System Error Messages 

By default, command procedures send system error messages to the file indicated 
by SYS$ERROR. You can redefine SYS$ERROR to direct system error messages 
to a specified file. However, if you redefine SYS$ERROR to be different from 
SYS$OUTPUT (or if you redefine SYS$OUTPUT without also redefining 
SYS$ERROR), DCL commands and images that use standard system error 
display mechanisms send system error level and system severe level error 
messages to both SYS$ERROR and SYS$OUTPUT. Therefore, you receive these 
messages twice— once in the file indicated by the definition of SYS$ERROR and 
once in the file indicated by SYS$OUTPUT. Success, informational, and warning 
level messages are sent only to the file indicated by SYS$OUTPUT. 

If you want to suppress system error messages from a DCL command, be sure 
that neither SYS$ERROR nor SYS$OUTPUT is equated to the terminal. For 
example, the following command procedure accepts a directory name as a 
parameter, sets the default to that directory, and purges files in the directory. To 
suppress system error messages, the procedure temporarily defines SYS$ERROR 
and SYS$OUTPUT as the null device. 

$ ! Purge files in a directory and suppress messages 
$ ! 

$ SET DEFAULT 'PI' 

$ ! Suppress messages 
$ ! 

$ DEFINE/USER_MODE SYS$ERROR NL: 

$ DEFINE/USER_MODE SYS$OUTPUT NL: 

$ PURGE 
$ EXIT 

You can also use the SET MESSAGE command to suppress system messages. For 
example: 
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$ ! Purge files in a directory and suppress system messages 
$ ! 

$ SET DEFAULT 'PI' 

$ ! Suppress system messages 
$ ! 

$ SET MESSAGE/NOFACILITY - 

/NOIDENTIFICATION - 
/NOSEVERITY - 
/NOTEXT 

$ PURGE 

$ SET MESSAGE/FACILITY - 

/IDENTIFICATION - 

/SEVERITY 

/TEXT 

$ EXIT 

Note that if you run one of your own images from a command procedure and 
the image references SYS$ERROR, the image sends system error messages only 
to the file indicated by SYS$ERROR— even if SYS$ERROR is different from 
SYS$OUTPUT. Only DCL commands and images that use standard system error 
display mechanisms send messages to both SYS$ERROR and SYS$OUTPUT 
when these files are different. 

For more information on SYS$ERROR and SYS$OUTPUT, see Chapter 13. 

15.4.2.5 Verifying Command Procedure Execution 

By default, only the output from commands and images is displayed when you 
execute command procedures interactively. The following commands verify 
command procedure execution and are useful for debugging command procedures: 

• SET VERIFY 

To display DCL command lines, data lines, and comment lines, use the 
SET VERIFY command within the command procedure or at the interactive 
command level. SET VERIFY displays each line before it is executed. When 
an error occurs with verification set, you see the error and the line that 
generated the error. In the following example, seeing the command line that 
generated the error explains the system error message: 

$ SET VERIFY 
$ 0CDIR 

$ ! Read a command from the terminal 
$ INQUIRE COMMAND - 

"Command (EXIT, DIRECTORY, TYPE, PURGE, DELETE, COPY) " 

Command (EXIT, DIRECTORY, TYPE, PURGE, DELETE, COPY) : DELETE 
$ COMMAND = F$EXTRACT (0,2, COMMAND) 

$GET_COMMAND : 

$ IF COMMAND .EQ. "EX" THEN GOTO END_COMMAND 
%DCL-W-IVCHAR, non-numeric character in value string 
\E\ EXIT 

$ IF COMMAND ,NES. "DI" THEN GOTO END_DIR 


$ SET NOVERIFY 

In this example, the logical operator .EQ. is used to compare numbers not 
strings. See Chapter 14 for information about logical operators. To correct 
the error, change .EQ. operator to .EQS. operator. 

Note that you can use keywords with the SET VERI FY command to indicate 
that only command lines or data lines are to be verified. See the Open VMS 
DCL Dictionary for more information. 
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The SET VERIFY command remains in effect until you log out, you enter 
the SET NOVERIFY command, or you use the F$VERI FY lexical function 
to change the verification setting. (Chapter 16 contains more information on 
changing verification settings.) 

• SET PREFIX 

If verification is in effect, you can also use the DCL command SET PREFIX 
to time-stamp a procedure log file by prefixing each command line with 
the time it is executed. The following example illustrates the use of time- 
stamping: 

$ SET VERIFY 
$ 0TEST 

$ SET DEFAULT SYS$L0GIN 
S SHOW DEFAULT 
USER$ : [SMYTHE] 

$ SET PREFIX "(!5%T) " 

$ 0TEST 

(17:52) $ SET DEFAULT SYS$L0GIN 

(17:52) S SHOW DEFAULT 
USER$ : [SMYTHE] 

For more information on time-stamping, see the description of the SET 
PREFIX command in the OpenVMS DCL Dictionary. 

• SHOW SYMBOL 

Use the SHOW SYMBOL command to display the values of the symbols 
involved in an error. In the following procedure, the IF statement is not 
passing control to the expected procedures. Putting the command SHOW 
SYMBOL COMMAND before the IF statement allows you to check the value 
of COMMAND. 

$ SET VERIFY 
$ 0CDIR 
$GET_COMMAND : 

$ ! Read a command from the terminal 
$ INQUIRE COMMAND- 

"Command (EXIT, DIRECTORY, TYPE, PURGE, DELETE, COPY) " 

Command (EXIT, DIRECTORY, TYPE, PURGE, DELETE, COPY) : DELETE 
$ COMMAND = F$EXTRACT (1,2, COMMAND) 

$ SHOW SYMBOL COMMAND 
COMMAND = "EL" 

$GET_COMMAND : 

$ IF COMMAND . EQS. "EX" THEN GOTO ENDJCOMMAND 


In this example, the F$EXTRACT lexical function extracts two 
characters beginning at character 1 (the second character), rather 
than at character 0 (the first character). To correct the error, change 
F$EXTRACT(1, 2, COMMAND) to F$EXTRACT(0, 2, COMMAND). Note that 
the I NQUI RE command automatically converts input to uppercase; therefore, 
the quoted string in the I F statement must be written in uppercase for DCL 
to eval uate the stri ngs as equal . 

You can also interrupt a command procedure while it is executing to enable 
verification. As long as the command procedure does not contain the SET 
VERIFY command or a Ctrl/Y key sequence, you can enable verification by 
following these steps: 

1. Press Ctrl/Y to interrupt execution. 
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2. Enter the SET VERI FY command. 

3. Enter the CONTINUE command to continue execution of the command 
procedure (with verification enabled). 

15.5 Reading and Writing Files (File I/O) 

The basic steps in reading and writing files from a command procedure are as 
follows: 

• Use the OPEN command to open a file. The OPEN command assigns a logical 
name to the file and specifies whether the file is to be read, written, or both 
read and written. Subsequent READ, WRITE, and CLOSE commands use 
this logical name to refer to the file. 

Note 

You do not have to open SYS$INPUT, SYS$OUTPUT, SYS$COMMAND, 
and SYS$ERROR explicitly to read or write to them because the system 
opens these files for you when you log in. For more information on 
reading or writing to these process-permanent files, see Section 15.4.2. 


• Use the READ or WRITE commands to read or write records to the file. One 
way to perform input and output to files is to design a loop to read a record, 
process the record, and write the modified record to either the same file or to 
another file. You then execute the commands in this loop (reading, processing, 
and writing records) until you are done. 

• Use the CLOSE command to close the file. Otherwise, the file remains open 
until you log out. 

The following sections describe how to use the OPEN, READ, WRITE, and 
CLOSE commands. I ncluded are descriptions of how to modify files and how to 
handle errors when you perform file operations. 

15.5.1 Opening a File 

The OPEN command opens sequential, relative, or indexed sequential files. 

The files are opened as process-permanent; they remain open for the duration 
of your process unless you explicitly close them (with the CLOSE command). 
While the files are open, they are subject to OpenVMS RMS restrictions on using 
process-permanent files. 

When you open a file, the OPEN command assigns a logical name (specified as 
the first parameter) to the file (specified as the second parameter) and places 
the name in the process logical name table. Subsequent READ, WRITE, and 
CLOSE commands use this logical name to refer to the file. I n the following 
example, the OPEN command assigns the logical name IN FILE to the file 
DISK4:[M URPHYjSTATS.DAT: 

$ OPEN/READ INFILE DISK4 : [MURPHY] STATS . DAT 
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Note 

The logical name in the OPEN command must be unique. If the OPEN 
command does not work and your commands seem correct, change the 
logical name in the OPEN command. To display a list of logical name 
definitions, use the SHOW LOGICAL command. 


To ensure that the command procedure can access the correct files, use complete 
file specifications (for example, DISK4:[M URPHYJSTATS.DAT) or use the SET 
DEFAULT command to specify the proper device and directory before you open a 
file. 

The following table describes how to open a file for reading, writing, or both 
reading and writing. 


Example 

Explanation 

Opening a File for Reading (OPEN/READ) 

$ OPEN/READ INFILE DISK4 : [MURPHY] STATS . DAT 
$ READ_FILE : 

$ READ /END_0F_F I LE=D0NE INFILE DATA 

$ GOTO READ_FILE 
$ DONE: 

$ CLOSE INFILE 

$ EXIT 

Opens the file STATS.DAT, assigns the 
logical name INFILE to the file, and places 
the record pointer at the beginning of the 
file. When you open a file for reading, you 
can read but not write records. Each time 
you read a record, the pointer moves to the 
next record. 

Opening a New File for Waiting (OPEN/WRITE 1 ) 

$ OPEN/WRITE OUTFILE DISK4 : [MURPHY] NAMES . DAT 
$ UPDATE: 

$ INQUIRE NEW_RECORD "Enter name" 

$ WRITE OUTFILE NEW_RECORD 
$ IF NEW_RECORD . EQS. "" THEN GOTO EXIT_C0DE 

$ GOTO UPDATE 

$ EXIT_CODE : 

$ CLOSE OUTFILE 

$ EXIT 

Creates a new file, NAMES.DAT, for writing 
and writes records to the file. The OPEN 
/WRITE command creates a sequential file in 
print file format. The record format for the 
file is variable with fixed control (VFC), with 
a 2-byte record header. 

If you specify a file that already exists, the 
OPEN/WRITE command opens a new file 
with a version number one greater than the 
existing file. 

Appending Data to an Existing File 
(OPEN/APPEND 1 ) 

$ OPEN/APPEND OUTFILE DISK4 : [MURPHY] NAMES . DAT 
$ INQUIRE NEW_RECORD "Enter name" 

$ WRITE OUTFILE NEW_RECORD 

Appends records to the end of an existing 
file, NAMES.DAT. If you attempt to open a 
file that does not exist, an error occurs and 
the file is not opened. 

$ CLOSE OUTFILE 



1_ rhe /WRITE and /APPEND qualifiers are mutually exclusive. 
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Example 


Explanation 


Opening a File for Reading and writing 
(OPEN/READ/WRITE) 

$ OPEN/READ/WRITE FILE DISK4 : [MURPHY] STATS . DAT 


Places the record pointer at the beginning 
of the file STATS.DAT so you can read the 
first record. When you use this method 


of opening a file, you can replace only the 
record you have read most recently; you 


cannot write new records to the end of the 
file. In addition, a revised record must be 
exactly the same size as the record being 
replaced. 


You can also open shareable files. The /SHARE qualifier enables other users to 
read (/SH ARE=READ) or write (/SHARE=WRITE) to the opened file. In addition, 
users can access shareable files with the DCL commands TYPE and SEARCH . 


15.5.2 Writing to a File 


To write to a file, use the following procedure: 

1. Open the file for writing (see Section 15.5.1). 

2. Begin the write loop with a label. 

File I/O is always done in a loop unless you are writing or reading a single 
record. 

3. Read the data to be written. 

Use the INQUIRE command or the READ command to read data into a 
symbol . 

4. Test the data. 

Check the symbol containing the data. If the symbol is null (for example, if 
you press Return and enter no data on the line), you have reached the end 
of the data to be written to the file and you should go to the end of the loop. 
Otherwise, continue. 

5. Write the data to the file. 

Use the WRITE command to write the value of the symbol (one record) to the 
file. 

6. Return to the beginning of the loop. 

You remain within the loop until there is no more data to be written to the 
file. 

7. End the loop and close the file (see Section 15.5.4). 

The following command procedure writes data to the new file STATS.DAT. If a file 
of that name exists, a new version is created. 
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$ ! Write a file 
$ ON ERROR THEN EXIT 
$ ! 

$ OPEN/WRITE IN_FILE DISK4 : [MURPHY] STATS . DAT 
$ ON C0NTR0L_Y THEN GOTO END_WRITE 
$ ! 

$ ON ERROR THEN GOTO END_WRITE 
$ ! 

$WRITE: 

$ INQUIRE STUFF "Input data" 

$ IF STUFF . EQS. "" THEN GOTO END_WRITE 
$ WRITE IN_FILE STUFF 
$ GOTO WRITE 
$END_WRITE : 

$ ! ! 

$ CLOSE IN_FILE 


Begin the loop 

Prompt for input 

Test for the end of the file 

Write to the file 

Go to the beginning 

End the loop 


Exit if the command procedure 


cannot open the file 
Open the file 

Close the file if you quit 


execution with Ctrl/Y 
Close the file if an error occurs 


Close the file 


To create a file with a unique name, use the F $SEARCH lexical function to 
see whether the name is already in the directory. (See the lexical function 
descriptions in the OpenVMS DCL Dictionary for more information about 
F$SEARCH .) The following command procedure prompts the user for a file name, 
then uses the F$SEARCFI lexical function to search the default directory for the 
name. If a file with that name already exists, control is passed to ERROR_l, the 
procedure prints the message 'The file already exists" and control returns to the 
label GET_NAME. The procedure then prompts for another file name. 

$ ! FILES.COM 
$ ! 

$GET_NAME: 

$ INQUIRE FILE "File" ! Prompt the user for a file name 

$ IF F$SEARCH (FILE) .NES. "" ! Make sure the file name is unique 

$ THEN 

$ WRITE SYS$OUTPUT "The file already exists" 

$ GOTO GET_NAME 
$ ELSE 

$ OPEN/WRITE IN_FILE 'FILE' ! Open the file with WRITE access 
$ END IF 


$ EXIT 


Specifying Data for the WRITE Command 

When you specify data for the WRITE command, follow the rules for character 
string expressions described in Chapter 14. The following example shows 
different ways of specifying data: 
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$! Define symbols 
S! 

$ CREATED = "File created April 15, 1994" 

S COUNT = 4 

$ P4 = "fourth parameter" 

$ ! 

$! Open the file DATA. OUT for writing 
$! 

$ OPEN/WRITE OUTFILE DISK4 : [MURPHY] DATA. OUT 


S! 

$ WRITE OUTFILE CREATED 1 

$ WRITE OUTFILE "CREATED" 2 

$ ! 

$ WRITE OUTFILE "Count is "COUNT'." 3 

$ WRITE OUTFILE P' COUNT' 4 

$! 

$ WRITE OUTFILE "Mode is "f$mode()'" 5 

S! 

$ CLOSE OUTFILE 


$ TYPE DISK4: [MURPHY] DATA. OUT [FtetUFiT] 6 

File created April 15, 1994 

CREATED 

Count is 4. 

fourth parameter 

Mode is INTERACTIVE 

S 

This example demonstrates the following methods of specifying data: 

1 Specifies the data to be written as a character string expression. The WRITE 
command automatically substitutes symbols and lexical functions. 

2 Writes the string CREATED to the output file as a literal character string. 
The WRITE command does not perform symbol substitution on strings 
enclosed in quotation marks. 

3 Combines literal strings with symbol names. To force symbol substitution, 
place the entire string within quotation marks and use double apostrophes 
before the symbol to identify it and a single apostrophe following it. 

Another way to combine literal strings with symbol names is to insert a 
comma before and after the symbol, place quotation marks around the 
delimited symbol, and enclose the entire character string in quotation marks. 
For example: 

$ WRITE OUTFILE "Count is ", COUNT,"." 

4 Uses an apostrophe in the WRITE command line to force symbol substitution. 

I n this example, the WRITE command substitutes a value for the symbol 
COUNT and performs symbol substitution on the resulting command string 
(P4). 

5 Combines literal strings and lexical functions by using the apostrophe to force 
symbol substitution within the character string. 

6 Displays the data written to the output file DATA. OUT by the preceding 
WRITE commands. 
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Writing Long Records 

When the WRITE command writes a record, it positions the record pointer after 
the record just written. The WRITE command can write a record that is up to 
2,048 bytes long. 

Use the /SYMBOL qualifier to write a record if either of the following conditions 
exist: 

• The record is longer than 1,024 bytes 

• An expression in the WRITE command is longer than 255 bytes 

See the description of the WRITE command in th eOpenVMS DCL Dictionary for 
more information on writing long records. 

Updating a Record 

You can use the WRITE command with the /UPDATE qualifier to change a record 
rather than insert a new one. To use the /UPDATE qualifier, you must open the 
file for both reading and writing (see Section 15.5.1). 

15.5.3 Reading from a File 

You can use the READ command to read records that are less than or equal to 
1,024 characters in length. To read data from a file, use the following procedure: 

1. Open the file for reading (see Section 15.5.1). 

2. Begin the read loop with a label. 

File I/O is always done in a loop unless you are reading or writing a single 
record. 

3. Read the data from the file. 

Use the READ command with the/END_OF_FILE qualifier to read a record 
and assign its contents to a symbol. The /END_OF_FI LE qualifier causes 
DCL to pass control to the label specified by the/END_OF_FILE qualifier 
when you reach the end of the file. Generally, you specify the label that 
marks the end of the read loop. 

4. Process the data. 

When you read a file sequentially, process the current record before reading 
the next one. 

5. Return to the beginning of the loop. 

You remain in the loop until you reach the end of the file. 

6. End the loop and close the file (see Section 15.5.4). 

The following command procedure reads and processes each record in the file 
STATS.DAT. The procedure executes the READ command repeatedly until the 
end-of-file status is returned. Then, the procedure branches to the line labeled 
END READ. 
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$ OPEN/READ INFILE DISK! : [MURPHY] STATS . DAT 
$ ! 

$READ_DATA: 

$ READ/END_OF_FILE=END_READ INFILE RECORD 


! Begin the loop 
!Read a record; test for 
! end of file 
! Process the data 


!0pen the file 


$ 

$ 


$ GOTO READ_DATA 
$ 

$END_READ : 

$ CLOSE INFILE 
$ EXIT 


!Go to the beginning of the loop 


!End of loop 
! Close the file 


When you specify a symbol name for the READ command, the command 
interpreter places the symbol name in the local symbol table for the current 
command level. If you use the same symbol name for more than one READ 
command, each READ command redefines the value of the symbol name. For 
example, in the preceding procedure, the READ command reads a new record 
from the input file (STATS.DAT) each time through the loop. It then uses this 
record to redefine the value of the symbol RECORD. 

Designing Read Loops 

When you read from files, you generally read and process each record until you 
reach the end of the file. By using The /END_OF_FI LE qualifier with the READ 
command, you can construct a loop to read records from a file, process the records, 
and exit from the loop when you have finished reading all the records. 

Note that the labels you specify for /END_OF_FI LE qualifiers are subject to the 
same rules as labels specified for a GOTO command (see Section 15.6.2). 

You should always use the /END_OF_FI LE qualifier when you use the READ 
command in a loop. Otherwise, when the error condition indicating the end-of-fi I e 
is returned by the OpenVMS Record Management Services (OpenVMS RMS), 
the command interpreter performs the error action specified by the current ON 
command. For example, OpenVMS RMS returns the error status %RMS-E-EOF. 
This causes a command procedure to exit unless the procedure has established its 
own error handling. 

Reading and Deleting Records from Indexed Sequential Files 

To read records randomly from indexed sequential files, use the READ command 
qualifiers /I NDEX and /KEY. These qualifiers specify that a record should be read 
from the file by finding the specified key in the index and returning the record 
associated with that key. If you do not specify an index, the primary index (0) is 
used. 

After you read a record randomly, you can read the remainder of the file 
sequentially by using READ commands without the /KEY or /I NDEX qualifiers. 

You can use the READ command with the /DELETE qualifier to delete records 
from indexed sequential files. The /DELETE qualifier causes a record to be 
deleted from a file after it has been read. Use the /DELETE qualifier with the 
/I NDEX and /KEY qualifiers to delete a record specified by a given key. 

For more information on the /DELETE, /INDEX, and /KEY qualifiers, see the 
description of the READ command in tbeOpenVMS DCL Dictionary. Use the 
READ command to read a record and assign its contents to a symbol. 
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15.5.4 Closing a File 

The CLOSE command closes a file and deassigns the logical name created by the 
OPEN command. I n the following example, the CLOSE command closes the file 
STATS.DAT and deassigns the logical name INFILE: 

$ OPEN INFILE DISK4: [MURPHY] STATS . DAT 


$ CLOSE INFILE 

Be sure to close all files you open in a command procedure before the command 
procedure terminates. If you fail to close an open file, the file remains open when 
the command procedure terminates and the logical name assigned to the open file 
is not deleted from the process logical name table. 

15.5.5 Modifying a File 

You can modify a file in the following ways: 

• U pdate records in the current version of the file. 

This method allows you to make minor changes to a small number of records 
in a file. Because this method does not allow you to change the size of a 
record or the number of records in the file, use it only for files with formatted 
records (for example, in a data file). 

In a sequential file, you can update individual records only if the revised 
records are exactly the same size as the existing records. I n an indexed 
sequential file, you can update individual records regardless of the record 
sizes. 

• Read records from an input file and create a new version of the file that 
incorporates your changes. 

This method allows you to change, delete, and insert records. You create a 
new file by using the old file as the main source of input. 

• Append records to the current version of the file. 

This method allows you to add new records to the end of the file. 

Updating Records in a File 

To make minor changes to the records in a file, use the following procedure: 

1. Open the file for both read and write access. 

2. Use the READ command to read through the file until you reach the record 
that you want to modify. 

3. Modify the record. In a sequential file, the text of this record must be exactly 
the same size as the original record. If the text of the modified record is 
shorter, pad the record with spaces, adding spaces to the end of the modified 
record until it is the same length as the original record. If the text of the 
modified record is longer, you need to create a new file (see Creating a Na/v 
Output File. 

4. Use the WRITE/UPDATE command to write the modified record back to the 
file. 

5. Repeat steps 2 to 4 until you have changed all records you intend to change. 

6. Use the CLOSE command to close the file. 
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After you close the file, it contains the same version number as when you started, 
even though individual records have been changed. 

The following command procedure shows how to make changes to a sequential 
file by reading and updating individual records: 

$! Open STATS.DAT and assign it the logical name FILE 

$ ! 

$ OPEN/READ/WRITE FILE DISK! : [MURPHY] STATS . DAT 
$ BEGIN_L00P : 

$! Read the next record from FILE into the symbol RECORD 

$ READ / END_OF_F I LE =END_LOOP FILE RECORD 

$! Display the record and see if the user wants to change it 

$! If yes, get the new record. If no, repeat loop 

S! 

$ PROMPT : 

$ WRITE SYS$OUTPUT RECORD 

$ INQUIRE/NOPUNCTUATION OK "Change? Y or N [Y] " 

$ IF OK . EQS. "N" THEN GOTO BEGIN_L00P 

$ INQUIRE NEW_RECORD "New record" 

$ ! Compare the old and new records 

$! If old record is shorter than new record, issue an error message 
$! If old record and new record are the same length, write the record 
$! Otherwise pad the new record with spaces so it is correct length 
$ ! 

$ 0LD_LEN = F$LENGTH (RECORD) 

$ NEW_LEN = F$LENGTH(NEW_RECORD) 

$ IF 0LD_LEN .LT. NEW_LEN THEN GOTO ERROR 

$ IF 0LD_LEN .EQ. NEW_LEN THEN GOTO WRITE_RECORD 

$ SPACES = " 

$ PAD = F$EXTRACT (0, OLD_LEN-NEW_LEN, SPACES) 

$ NEW_RECORD = NEW_RECORD + PAD 

$ ! 

$ WRITE_RECORD : 

$ WRITE/UPDATE FILE NEW_RECORD 

$ GOTO BEGIN_LOOP 

$ ! 

$ ERROR: 

$ WRITE SYS$OUTPUT "Error — New record is too long" 

$ GOTO PROMPT 


S! 

$ 

$ 

S 


END_LOOP : 


CLOSE FILE 
EXIT 


The following command procedure reads each record in a data file. The system 
displays the record on the terminal and you are asked whether the record needs 
to be modified. If you choose to modify the record, a new record is read from the 
terminal and its length is compared to the length of the original record. If the 
original record is longer, extra spaces make the new record the same size. If the 
original record is shorter, the system displays an error message and you are again 
prompted for a new record. If you choose not to modify the record, the next record 
is read from the file. 

$ ! MODIFY.COM 

S ! 

$ SPACES = " " ! Initialize string of spaces 

S ! to make new record same size 

$ OPEN/READ/WRITE FILE STATS.DAT ! Open the file for reading and writing 
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$ ! 

$BEGIN_LOOP: ! Begin the loop 

$ ! 

$ READ / END_OF_F I LE =END_LOOP FILE RECORD ! Read and display a record 
$ PROMPT : 

$ WRITE SYS$OUTPUT RECORD 
$ ! Does the user want to change the record? 

$ INQUIRE/NOPUNCTUATION YN "Do you want to change this data? [N] " 

$ ! 

$ IF YN . EQS. "Y" 

$ THEN 

$ ! Get the new record 

$ INQUIRE NEW_RECORD "New Record" 

$ 0LD_LEN = F$LENGTH (RECORD) 

$ ! Compare the old and new records 

$ IF 0LD_LEN .GE. F$LENGTH (NEW_RECORD) 

$ THEN 

$ IF 0LD_LEN .NE. F$LENGTH (NEW_RECORD) 

$ THEN 

$ ! New record shorter than old record 

$ PAD = F$EXTRACT (0, OLD_LEN-F$ LENGTH (NEW_RECORD) , SPACES) 

$ NEW_RECORD = NEW_RECORD + PAD 

$ END IF 

$ ! Write the new record 

$ WRITE/UPDATE FILE NEW_RECORD 

$ ELSE 

$ ! New record longer than old record 

$ WRITE SYS$OUTPUT "ERROR — New record is too long" 

$ GOTO PROMPT 

$ ENDIF 

$ ENDIF 

$ ! Get the next record 
$ GOTO BEGIN_LOOP 
$ ! 

$END_LOOP : 

$ CLOSE FILE 
$ EXIT 

Creating a New Output File 

To make extensive changes to a file, open that file for read access and open a new 
file for write access. Because you are creating a new output file, you can modify 
the size of records, add records, or delete records. 

The /WRITE qualifier opens a new file for write access. The new file can have the 
same name as the original file and a version number one higher than the version 
number of the old file. 


Note 

To ensure that the correct file is opened for reading, you must open the 
existing file for read access before you open the new version for write 
access. 


To make major modifications to a file, use the following procedure: 

1. Open the file for read access. This is the input file, the file you are modifying. 

2. Open a new file for write access. This is the output file, the file that you 
are creating. If you give the output file the same name as the input file, the 
output file will have a version number one greater than the input file. 

3. Use the READ command to read each record from the file you are modifying. 
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As you read each record from the original file, decide how the record is to be 
treated. I n the following examples, the symbol RECORD contains the record 
read from the original file: 

• No change— Write the same symbol to the new file. 

$ ! No change 
$ WRITE NEW_FILE RECORD 

• Change— Use the I NQUI RE command to read a different record into the 
symbol, then write the modified symbol to the new file. 

$ ! Change 

$ INQUIRE NEW_RECORD "New record" 

$ WRITE NEW_FILE NEW_RECORD 

• Delete— Do not write the symbol to the new file. 

• I nsert— Use a loop to read records into the symbol and to write the symbol 
to the new file as shown in the following example: 

$ ! Insertion 
$LOOP : 

$ !Get new records to insert 
$ INQUIRE NEW_RECORD "New record" 

$ IF RECORD . EQS. "" THEN GOTO END_L00P 
$ WRITE NEW_FILE NEW_RECORD 
$ GOTO LOOP 
$END_LOOP : 

4. Continue reading and processing records until you have finished. 

5. Use the CLOSE command to close both the input file and the output file. 

The following example shows a command procedure that reads a record from an 
input file, processes the record, and copies the record into an output file. 

$! Open STATS.DAT for reading and assign it 
$! the logical name INFILE 

$! Open a new version of STATS.DAT for writing 
$! and assign it the logical name OUTFILE 
$ ! 

$ OPEN/READ INFILE DISK4 : [MURPHY] STATS . DAT 
$ OPEN/WRITE OUTFILE DISK4 : [MURPHY] STATS . DAT 

S! 

$ BEGIN_L00P : 

$! Read the next record from INFILE into the symbol RECORD 

$ ! 

$ READ / END_OF_F I LE =END_LOOP INFILE RECORD 

$! Display the record and see if the user wants to change it 

$! If yes, get the new record 

$! If no, write record directly to OUTFILE 

S! 

$ PROMPT : 

$ WRITE SYS$OUTPUT RECORD 

$ INQUIRE/NOPUNCTUATION OK "Change? Y or N [Y] " 

$ IF OK .EQS. "N" THEN GOTO WRITE_RECORD 

$ INQUIRE RECORD "New record" 

$ ! 

$ WRITE_RECORD: 

$ WRITE OUTFILE RECORD 

$ GOTO BEGIN_L00P 

$ ! 

$! Close input and output files 

$ ! 

$ END_LOOP : 
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$ CLOSE INFILE 

$ CLOSE OUTFILE 

$ EXIT 

Appending Records to a File 

The OPEN/APPEND command appends records to the end of an existing file. Use 
the following steps to append records to a file: 

1. Use the OPEN command with the /APPEND qualifier to position the record 
pointer at the end of the file. The /APPEND qualifier does not create a new 
version of the file. 

2. Use the WRITE command to write new data records. Continue adding records 
until you are finished. 

3. Use the CLOSE command to close the file. 

The following example appends new records to a file: 

$! Open STATS.DAT to append files and assign 
$! it the logical name FILE 
$! 

$ OPEN/APPEND FILE DISK4 : [MURPHY] STATS . DAT 
$ ! 

$ BEGIN_L00P : 

$ ! Obtain record to be appended and place this 
$ ! record in the symbol RECORD 
$ ! 

$ PROMPT: 

$ INQUIRE RECORD - 

"Enter new record (press RET to quit) " 

$ IF RECORD .EQS . "" THEN GOTO END_LOOP 

$! Write record to FILE 
$! 

$ WRITE FILE RECORD 

$ GOTO BEGIN_LOOP 

$! 

$! Close FILE and exit 
$ ! 

$ END_L00P : 

$ CLOSE FILE 

$ EXIT 

15.5.6 Handling File I/O Errors 

Use the /ERROR qualifier with the OPEN, READ, or WRITE command to 
suppress system error messages and to pass control to a specified label. If an 
error occurs during an input or output operation, the /ERROR qualifier overrides 
all other error-control mechanisms (except the/END_OF_FILE qualifier on the 
READ command). For example, in the following command procedure, if an 
error occurs during execution of the OPEN command, the procedure returns the 
message "Error opening STAT.DAT" and exits: 

$ OPEN/READ/ERROR=READ_ERR 0UT_F STAT.DAT 


$ EXIT 
$READ_ERR: 

$ WRITE SYS$OUTPUT "Error opening STAT.DAT" 
$ EXIT 
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The following example uses the /ERROR qualifier with the OPEN command: 

$ OPEN/READ/ERROR=CHECK FILE CONTINGEN.DOC 


S CHECK: 

$ WRITE SYS$OUTPUT "Error opening file" 

The OPEN command requests that thefileCONTINGEN.DOC be opened for 
reading. If the file cannot be opened (for example, if the file does not exist), the 
OPEN command returns an error condition and transfers control to the CHECK 
label. 

The error path specified by the /ERROR qualifier overrides the current ON 
condition established for the command level. If an error occurs and the target 
label is successfully given control, the reserved global symbol $STATUS retains 
the code for the error. You can use the F$MESSAGE lexical function in your 
error-handling routine to display the message in $STATUS. For example: 

S OPEN/READ/ERROR=CHECK FILE 'PI' 


S CHECK: 

$ ERR_MESSAGE = F$MESSAGE ($STATUS) 

$ WRITE SYS$OUTPUT "Error opening file: ",P1 
$ WRITE SYS$OUTPUT ERR_MESSAGE 


If an error occurs while you are using the OPEN, READ, WRITE, or CLOSE 
command and you do not specify an error action, the current ON command action 
is taken. (See Section 15.7.) 

When a READ command receives an end-of-file message, the error action is 
determined in the following way: 

• If you use the /END_OF_FI LE qualifier, control is passed to the specified 
label. 

• If you do not use the /END_OF_FI LE qualifier, control is passed to the label 
specified with the /ERROR qualifier. 

• If you do not specify either qualifier (/END_OF_FI LE or /ERROR), the current 
ON command action is taken. 

15.6 Techniques for Controlling Execution Flow 

Command procedures can perform program-like functions. You can use variable 
input in a command procedure, execute sections of the procedure only if certain 
conditions are true, execute subroutines, or invoke other command procedures. 

The normal flow of execution in a command procedure is sequential: the 
commands in the procedure execute in order until the end of the file is reached. 
However, you can also control whether certain statements are executed or the 
conditions under which the procedure should continue executing. 

This section discusses the DCL commands you can use to control or alter the flow 
of execution in a command procedure. They are as follows: 
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• IF 

Tests the value of an expression and executes a command or block of 
commands following the THEN command if the result of the expression 
is true. If the result of the expression is false and the ELSE command is 
specified, the command or block of commands following the ELSE command 
execute. 

• GOTO 

Transfers control to a labeled line in the procedure. 

• GOSUB 

Transfers control to a labeled subroutine in a command procedure but does 
not create a new command level. 

• CALL 

Transfers control to a labeled subroutine in a command procedure and creates 
a new command level. 

• EXIT 

Terminates the current procedure and returns control to the previous 
command level. 

• STOP 

Terminates the current procedure and returns to command level 0. 

You can also use the execute procedure ( @) command to invoke (or call) another 
command procedure and create another command level. For more information, 
see Section 15.1.4. 

15.6.1 Using the IF Command 

The I F command tests the value of an expression and executes a command or 
block of commands when the result of the expression is true. When the result of 
the expression is false, one of the following occurs: 

• When one command follows theTHEN command, it is not executed and the 
following command executes. 

• When a block of commands follows theTHEN command and the ELSE 
command is not specified, the command immediately following the ENDIF 
command executes. 

• When the ELSE command is specified, the command or block of commands 
following the ELSE command executes. 

DCL provides two distinct formats for the I F command. The first format executes 
a single command when the expression specified to the I F command is true as 
follows: 

$ IF expression THEN [$] command 

DCL also provides a block-structured IF format. The block-structured IF 
command executes more than one command if the expression specified is true and 
accepts an optional ELSE statement, which executes one or more commands if 
the expression is false. 
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To execute more than one command when an expression is true, specify the 
THEN command as a verb (a DCL command preceded by a dollar sign) and 
terminate the resulting block-structured statement with an ENDIF statement, as 
follows: 

$ IF expression 
S THEN 
$ command 
S command 


S ENDIF 

To execute one or more commands when an expression is false, specify the ELSE 
statement as a verb and terminate the resulting block-structured statement with 
an ENDIF statement, as follows: 

$ IF expression 
$ THEN 
$ command 
S command 


$ ELSE 
S command 
$ command 


$ ENDIF 

Command blocks can be executed in several ways, depending on whether you 
leave the commands in the same command procedure or put them in another 
command procedure and execute them there: 

• If you leave the commands in the command procedure, place them after the 
THEN statement, as in this example: 

$ IF condition 
$ THEN command 
command 


$ ENDIF 

• If you place the commands in a separate procedure, make the call to that 
command procedure as part of the THEN statement, as in this example: 

$ IF condition 
$ THEN @command_procedure 
$ ELSE command 
$ command 

$ ENDIF 

You can continue to specify the nonblock-structured I F format and direct flow to a 
labeled region when the condition specified is met, as follows: 

$ IF not condition THEN GOTO END_LABEL 


$END_LABEL: 
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In the following example, a specified file is purged if COMMAND equals "PU." If 
COMMAND does not equal "PU," a specified file is printed. 

$! Purge a file. If no file exists, print the requested file. 

$ IF COMMAND . EQS. "PU" 

$ THEN 

$ INQUIRE FILESPEC "File to purge" 

$ PURGE 'FILESPEC' 

$ ELSE 

$ INQUIRE FILESPEC "File to print" 

$ PRINT 'FILESPEC' 

$ ENDIF 

$!Type a file. If no file exists, exit" 

$ IF COMMAND .EQS. "TY" 


$ EXIT 

In the following example, the command procedureSCREEN_SETUP.COM is 
executed if F $M ODE () equals "INTERACTIVE". If F$MODE() does not equal 
"INTERACTIVE", the procedure exits. (The command procedure SCREE N_ 
SETUP.COM would be in a separate file; the commands it contains are shown 
indented here for clarity.) 

$ IF F$MODE() .EQS. "INTERACTIVE" 

$ THEN 

$ @SCREEN_SETUP 

$ ! SCREEN_SETUP.COM 
$ ! Set terminal characteristics 
$ SET TERMINAL/DEVICE=VT200 
$ SET TERMINAL/WIDTH=132 
$ ! Invoke Editor 
$ EVE :== EDIT/TPU 
$ ELSE 
$ EXIT 
$ ENDIF 


When you use the I F-TFI EN-ELSE language construct, observe the following 
restrictions: 

• I nclude no more than 16 levels of nested I F statements. 

• Terminate a command block started by a THEN statement with either an 
ELSE or an ENDIF statement. 

• Terminate a command block started by an ELSE statement with an ENDIF 
statement. 

• I nclude a TH EN statement as the first executable statement following an I F 
statement. 

• Do not specify a label on a line containing a THEN or an ELSE statement. 
You can, however, specify a label on a line containing an ENDIF statement. 
Programs can branch within the current command block but branching into 
the middle of another command block is not recommended. 
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The expression following the I F command can consist of one or more numeric 
constants, string literals, symbolic names, or lexical functions separated by 
logical, arithmetic, or string operators. An expression is true when it has one of 
the following values: 

• An odd integer value 

• A character string value that begins with any of the letters Y, y, T, or t 

• A character string value that contains numbers that form an integer with an 

odd value (for example, the string "27") 

An expression is false when it has one of the following values: 

• An even integer value 

• A character string value that begins with any letter other than Y, y, T, or t 

• A character string value that contains numbers that form an integer with an 

even value (for example, the string "28") 

When you write an expression for an I F command, follow the rules for writing 
expressions given in Section 14.6. In particular, remember the following: 

• When you use symbols in IF statements, their values are automatically 
substituted. Do not use apostrophes ( ' ) as substitution operators unless you 
need to force iterative translation. 

• String comparison operators end in the letter S. For example, use operators 
such as .EQS., .LTS., and .GTS. to compare strings. By contrast, the operators 
.EQ., .LT., and .GT. are used for comparing integers. 

• When you test to see whether two strings are equal, the strings must use the 
same case in order for DCL to find a match. That is, the string "COPY" does 
not equal the string "copy" or the string "CoPy." 

The following examples illustrate expressions that can be used with the I F 
command. (For additional examples, see the description of the IF command in 
the OpenVMS DCL Dictionary.) The first example uses a logical operator and 
executes only one command following theTFIEN statement: 

S INQUIRE CONT "Do you want to continue [Y/N] " 

$ IF .NOT. CONT THEN EXIT 


I n this example, when the symbol CONT is not true, the procedure exits. 

The following example uses a symbol and a label within the I F expression: 

$ INQUIRE CHANGE "Do you want to change the record [Y/N] " 

$ IF CHANGE THEN GOTO GETJCHANGE 

$ GETJCHANGE : 


In this example, when the symbol CHANGE is true, the procedure transfers 
control to the label GET_CHANGE. Otherwise, the procedure executes the 
command following the I F command. 
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The following example illustrates two different I F commands. The first I F 
command compares two integers; the second I F command compares two strings. 
Note that the .EQ. operator is used for the integer comparison and the .EQS. 
operator is used for the string comparison. 

$ COUNT = 0 
$ LOOP: 

$ COUNT = COUNT + 1 
$ IF COUNT .EQ. 9 THEN EXIT 

$ IF P' COUNT' .EQS. "" THEN EXIT 


$ GOTO LOOP 

First, the value of COUNT is compared to the integer 9. When the values 
are equal, the procedure exits; when the values are not equal, the procedure 
continues. The loop terminates after eight parameters (the maximum number 
allowed) have been processed. 

I n the second I F expression, the string value of the symbol P'COUNT' is compared 
to a null string to see whether the symbol is undefined. Note that you must use 
apostrophes to force iterative substitution of the symbol COUNT. For example, 
when COUNT is 2, the result of the first translation is P2. Then, the value of P2 
is used in the string comparison. 

You can execute a block of commands after theTFIEN command when the result 
of the I F expression is true. When you use a block of commands, place the THEN 
command as the first command on the line following the I F command. I n the 
following example, two SET TERMINAL commands execute and the procedure 
transfers control to the label PROCEED when F$MODE equals "I NTERACTIVE". 
When F$MODE does not equal "INTERACTIVE", the procedure exits. 

$ IF F$M0DE () .EQS. "INTERACTIVE" 

$ THEN 

$ SET TERMINAL/DEVICE=VT200 

$ SET TERMINAL/WIDTH=132 

$ GOTO PROCEED 
$ ENDIF 
$ EXIT 
$PROCEED: 

The following example illustrates how to use a block of commands with the 
IF command in conjunction with the ELSE command. When the condition is 
true, the procedure writes a message to SYS$OUTPUT and executes the SHOW 
DEVICE and SET DEVICE commands. When the condition is not true, the 
procedure writes two messages to SYS$OUTPUT. 

$ INQUIRE DEV "Device to check" 

$ IF F$GETDVI (DEV, "EXISTS") 

$ THEN 

$ WRITE SYS$OUTPUT "The device exists." 

$ SHOW DEVICE 'DEV' 

$ SET DEVICE/ERROR_LOGGING 'DEV' 

$ ELSE 

$ WRITE SYS$OUTPUT "The device does not exist." 

$ WRITE SYS$OUTPUT "Error logging has not been enabled." 

$ ENDIF 
$ EXIT 
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You can also execute a separate command procedure when the result of the I F 
expression is true. The following example executes the command procedure 
EXIT_ROUTINE.COM when the result of the I F expression is true: 

$ GET_COMMAND_LOOP : 

S INQUIRE COMMAND - 

"Enter command (DELETE, DIRECTORY, EXIT, PRINT, PURGE, TYPE) " 

$ IF COMMAND .EQS . "EXIT" THEN @EXIT_ROUTINE 

15.6.2 Using the GOTO Command 

The GOTO command passes control to a labeled line in a command procedure. 
You can precede any command string in a command procedure with a label. The 
following list summarizes the rules for entering labels: 

• Must be the first item on a line after the dollar sign 

• Can include up to 255 characters 

• Cannot contain embedded space characters 

• Must end with a colon 
For example: 

$ GOTO BYPASS 


$ BYPASS: 

As the command interpreter encounters labels, it enters them in a special section 
of the local symbol table. The amount of space available for labels is limited. If a 
command procedure uses many symbols and contains many labels, the command 
interpreter might run out of symbol table space and issue an error message. If 
this occurs, include the DELETE/SYMBOL command in your procedure to delete 
symbols as they are no longer needed. 

If a command procedure uses the same label more than once, the new definition 
replaces the existing one in the local symbol table. When duplicate labels exist, 
the GOTO command transfers control to the label that DCL has processed most 
recently. The GOTO command uses the following rules when processing duplicate 
labels: 

• If all duplicate labels precede the GOTO command, control transfers to the 
label nearest the GOTO command. 

• If duplicate labels precede and follow the GOTO command, control transfers 
to the preceding label nearest the GOTO command. 

• If all duplicate labels follow the GOTO command, control transfers to the 
label nearest the GOTO command. 

The GOTO command is especially useful within a THEN clause to cause a 
procedure to branch forward or backward. For example, when you use parameters 
in a command procedure, you can test the parameters at the beginning of the 
procedure and branch to the appropriate label: 
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$ IF PI .NES. "" THEN GOTO OKAY 
$ INQUIRE PI "Enter file spec" 

$ OKAY: 

$ PRINT / COP IES= 10 'PI' 


I n this example, the I F command checks that PI is not a null string. If PI is 
a null string, the GOTO command is not executed and the INQUIRE command 
prompts for a parameter value. Otherwise, the GOTO command causes a branch 
around the I NQUI RE command. I n either case, the procedure executes the 
PRI NT command following the line labeled OKAY. 

The target label of a GOTO or GOSUB command cannot be inside either a 
separate IF-THEN-ELSE construct or a separate subroutine. For example, the 
GOTO command in the following command procedure returns an error message: 

$ GOTO TEST_1 
$ EXIT 
$ IF l.EQ.l 

$ THEN WRITE SYS$OUTPUT "What are we doing here?" 

$ TEST_1 : 

$ WRITE SYS$OUTPUT "Got to the label" 

$ ENDIF 
$ EXIT 

You can also use the GOTO command to avoid reexecuting parts of the job that 
have completed successfully. To do this, follow these steps: 

1. Begin each possible starting point in the procedure with a label. After the 
label, use the SET RESTART_VALUE = label-name command to set the 
restarting point to that label. If the batch job is interrupted after the SET 
RESTART_VALUE = label-name command executes, the system assigns the 
appropriate label name to the global symbol BATCH $RE START when the 
batch job restarts. 

2. At the beginning of the procedure, test the value of the symbol $RE START. 

If $RE START is true, execute a GOTO statement using the symbol 
BATCH $RESTART as the transfer label. 

$RE START is a reserved global symbol that the system maintains for you. 
$RE START is true if one of your batch jobs was restarted after it was 
interrupted. Otherwise, $RESTART is false. You cannot delete the reserved 
global symbol $RE START. 


Note 

Most of your process environment is not maintained when the system 
fails. The only symbols maintained across a system failure are 
$RESTART and BATCH $RESTART. Therefore, you should redefine 
any symbols or process logical names used in your command procedure 
after each SET RESTART_VALUE command or in a THEN block that 
executes if $RESTART is true. If you define symbols and logical names 
in a THEN block, the command GOTO 'BATCH $RE START' should be the 
last command in the THEN block. 


If a command procedure has SET RESTART_VALUE commands in it but you 
want the job to reexecute in its entirety, enter the SET ENTRY/NOCH ECKPOI NT 
command to delete the global symbol BATCH $RESTART. 
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The following command procedure shows how to use restart values in a batch job: 

S ! Set default to the directory containing 
$ ! the file to be updated and sorted 
$ SET DEFAULT DISKI : [ACCOUNTS . DATA84 ] 

$ 

$ ! Check for restarting 
$ IF $ RESTART THEN GOTO ' BATCH$RESTART' 

S 

$ UPDATE_FILE : 

$ SET RESTART_VALUE = UPDATE_FILE 


$ S0RT_FILE : 

$ SET RESTART_VALUE = S0RT_FILE 


EXIT 

To submit this command procedure as a batch job that can be restarted, use the 
/RESTART qualifier to the SUBMIT command when you submit the job. If you 
restart a job that was interrupted, the job starts executing in the section where 
it was interrupted. For example, if the job is interrupted during the SORT_FI LE 
routine, it starts executing at the label SORT_FILE when it is restarted. 

15.6.3 Using the GOSUB Command 

The GOSUB command transfers control to a labeled subroutine in a command 
procedure. If the label does not exist in the command procedure, the procedure 
cannot continue executing and is forced to exit. You can nest the GOSUB 
command up to 16 times per procedure level. 

The GOSUB command is a local subroutine call; it does not create a new 
procedure level. Consequently, all labels and local symbols defined in the current 
command level are available to a subroutine invoked with GOSUB. 

The following list summarizes the rules for entering subroutine labels: 

• Must appear as the first item on a line after the dollar sign 

• Can have up to 255 characters 

• Cannot contain embedded space characters 

• Ends with a colon 

As the command interpreter encounters a label, it enters it in a special section of 
the local symbol table. The amount of space available for labels is limited. If a 
command procedure uses many symbols and contains many labels, the command 
interpreter may run out of table space and issue an error message. If this occurs, 
include the DELETE/SYMBOL command in your procedure to delete symbols as 
they are no longer needed. 

If a command procedure uses the same label more than once, the new definition 
replaces the existing one in the local symbol table. When duplicate labels exist, 
the GOSUB command transfers control to the label that DCL has processed 
most recently. Thus, if all duplicate labels precede the GOSUB command or all 
follow the GOSUB command, control transfers to the nearest GOSUB command. 
Flowever, if the duplicate labels precede and follow the GOSUB command, control 
transfers to the preceding label nearest the GOSUB command. 
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The RETURN command terminates a subroutine and returns control to the 
command following the GOSUB command. You can specify a value for $STATUS 
with the RETURN command that overrides the value that DCL assigns to 
$STATUS at the end of the subroutine. This value must be an integer between 
zero and four or an equivalent expression. If you specify a value for $STATUS, 
DCL interprets this value as a condition code. If you do not specify a value for 
$STATUS, the current value of $STATUS is saved. See Section 15.7 for more 
information about condition codes and $STATUS. 

The following example shows how you can use the GOSUB command to transfer 
control to subroutines: 

$ ! 

$ ! GOSUB.COM 
$! 

$ SHOW TIME 

$ GOSUB TEST1 1 

$ WRITE SYS$0UTPUT "GOSUB level 1 has completed successfully." 

$ SHOW TIME 
$ EXIT 
$! 

$ ! TEST1 GOSUB definition 
$! 

$ TEST1 : 

$ WRITE SYS$0UTPUT "This is GOSUB level 1." 

$ GOSUB TEST2 2 

$ RETURN %X1 3 

$! 

$ ! TEST2 GOSUB definition 
$! 

$ TEST2 : 

$ WRITE SYS$0UTPUT "This is GOSUB level 2." 

$ WAIT 00:00:02 

$ RETURN 4 

When this command procedure is executed, the following actions occur: 

1 The first GOSUB command transfers control to the subroutine labeled TEST1. 

2 The procedure executes the commands in subroutine TEST 1, branching to the 
subroutine labeled TEST2. 

3 The RETURN command in subroutine TEST1 returns control to the main 
command procedure and passes a value of 1 to $STATUS, indicating 
successful completion. 

4 The RETURN command in subroutine TEST2 returns control to subroutine 
TEST1. Note that this command executes before command 3. 

15.6.4 Using the CALL Command 

The CALL command transfers control to a labeled subroutine in a command 
procedure and creates a new procedure level. The CALL command allows you 
to keep more than one related command procedure in a single file, making the 
procedures easier to manage. The subroutine label, which must be unique, can 
precede or follow the CALL command in the command procedure. Section 15.6.3 
contains rules for entering subroutine labels. 

In addition to the label, you can pass up to eight optional parameters to the 
subroutine. These parameters assign character string values to the symbols PI 
to P8. Separate each parameter with one or more spaces. Use quotation marks 
( " " ) to specify a null parameter. Use alphanumeric and special characters to 
specify parameters, with the following restrictions: 
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• The command interpreter converts alphabetic characters to uppercase and 
uses spaces to delimit each parameter. To pass a parameter that contains 
embedded spaces or literal lowercase letters, place the parameter within 
quotation marks ( " " ). 

• If the first parameter begins with a slash character (/), enclose the parameter 
in quotation marks ( " " ). 

• If the parameter contains literal quotation marks and spaces, enclose the 
entire string in quotation marks and use a double set of quotation marks 
within the string. The following example equates the string /Va/ar say "quit" 
to PI. 

$ CALL SUB1 "Never say ""quit""" 

• To use a symbol as a parameter, enclose the symbol with apostrophes. ( "). 

$ CALL SUB2 'WHOLE' 

By default, the CALL command sends output to SYS$OUTPUT. The CALL 
command has an optional /OUTPUT qualifier that allows you to direct output 
from the subroutine to a file. The default file type for the output file is .LIS. Do 
not use wildcard characters in the output file specification. 

You can nest subroutines called with the CALL command and procedures called 
with the execute procedure (@) command to a maximum of 32 command levels. 
Unless they are masked using the SET SYMBOL command, local symbols defined 
in an outer level are available to any inner procedure or subroutine levels and 
global symbols are available at any command level. Labels are valid only for the 
level in which they are defined. 

The SUBROUTI NE and ENDSUBROUTI NE commands define the beginning 
and the end of a CALL subroutine. The label defining the entry point to the 
subroutine immediately precedes the SUBROUTINE command. You can place 
the EXIT command immediately before the ENDSUBROUTI NE command but it 
is not required to terminate the subroutine. The ENDSUBROUTI NE command 
terminates the subroutine and transfers control to the command line immediately 
following the CALL command. 

Command lines in a subroutine execute only when the subroutine is called 
with the CALL command. During the line-by-line execution of the command 
procedure, the command language interpreter skips all commands between the 
SUBROUTINE and the ENDSUBROUTI NE commands. 

The following restrictions apply to defining the scope of subroutine entry points 
and the use of label references: 

• Subroutine entry points that are defined within another subroutine are local 
to that subroutine. You cannot call a subroutine if the subroutine entry point 
is within a separate subroutine block. For example, the following call is not 
valid: 

$ CALL BAR 
$ 

$ MALN : SUBROUTINE 
$ 

$ BAR: SUBROUTINE 

$ END SUBROUTINE 

$ 

$ ENDSUBROUTINE 
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The following call is valid because BAR is defined within MAI N : 

$ MAIN: SUBROUTINE 
$ 

$ BAR: SUBROUTINE 

S ENDSUBROUTINE 

$ 

$ CALL BAR 
$ ENDSUBROUTINE 

• If a subroutine entry point is located within an IF-THEN-ELSE block, you 
cannot call this subroutine from outside the I F-THE N-ELSE block. For 
example, the following call is not allowed: 

$ IF 1 
$ THEN 

$ F00: SUBROUTINE 

$ ENDSUBROUTINE 
S ENDIF 
S CALL F00 

• Every SUBROUTI NE command must have a matching ENDSUBROUTI NE 
command to delimit the subroutine. 

In the following example, the entry point for subroutine B is defined within 
subroutine A because there is no ENDSUBROUTI NE to delimit A (that is, 
EXIT is not a delimiter of A). Therefore, subroutine B is inaccessible from 
outside subroutine A. 

$ A: SUBROUTINE 
S EXIT 
$ 

$ B: SUBROUTINE 
$ ENDSUBROUTINE 

The following example includes two subroutines called SUB1 and SUB2. The 
subroutines do not execute until they are called with the CALL command. 

$ 

$ ! CALL.COM 
$ 

$! Define subroutine SUB1. 

$ ! 

$ SUB1 : SUBROUTINE 


$ 


CALL SUB2 ! Invoke SUB2 from within SUB1. 


$ @FILE ! Invoke another command procedure file. 


$ EXIT 

$ ENDSUBROUTINE !End of SUB1 definition. 

$! 

$! Define subroutine SUB2 . 

$ ! 

$ SUB2 : SUBROUTINE 
$ EXIT 

$ ENDSUBROUTINE !End of SUB2 definition. 

$ ! 

$! Start of main routine. At this point, both SUB1 and SUB2 
$! have been defined but none of the previous commands have 
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$! been executed. 

S! 

$ START: 

$ CALL/OUTPUT=NAMES . LOG SUB1 "THIS IS PI" 


$ CALL SUB2 "THIS IS PI" "THIS IS P2" 


$ EXIT !Exit this command procedure file. 

In this example, the CALL command invokes the subroutine SUB1 and directs 
output to the file NAMES.LOG. Subroutine SUB1 calls subroutine SUB2. The 
procedure executes SUB 2, invoking the command procedureFILE.COM with 
the execute procedure (@) command. When all the commands in SUB1 have 
executed, the CALL command in the main procedure calls SUB2 a second time. 
The procedure exits when SUB2 finishes executing. 

15.6.5 Writing Loops 

A loop is a group of statements that execute repeatedly until a condition is met. 
When you write loops, do the following: 

1. Begin the loop with a label. 

2. Test a variable to determine whether you need to execute the commands in 
the loop. (This is the termination variable.) 

3. If you do not need to execute the loop, go to the end of the loop. 

4. If you need to execute the loop, perform the commands in the body of the loop 
then return to the beginning of the loop. 

5. End the loop. 

You can also write loops that test the termination variable at the end of the loop 
as follows: 

1. Begin the loop. 

2. Perform the commands in the body of the loop. 

3. Change the termination variable. 

4. Test the termination variable. If the condition is not met, go to the beginning 
of the loop. 

5. End the loop. 

Note that when you test the termination variable at the end of the loop, the 
commands in the body of the loop are executed at least once, regardless of the 
value in the termination variable. 

Both of the following examples execute a loop that terminates when COMMAND 
equals “EX” (EXIT). F$EXTRACT truncates COMMAND to its first two 
characters. In the first example, COMMAND, the termination variable, is 
tested at the beginning of the loop; in the second, it is tested at the end of the 
loop: 


15-45 


Command Procedures: Programming with DCL 
15.6 Techniques for Controlling Execution Flow 


$ ! EXAMPLE 1 

$ ! 

$GET_COMMAND : 

$ INQUIRE COMMAND- 

"Command (EXIT, DIRECTORY, TYPE, PURGE, DELETE, COPY) " 
$ COMMAND = F$EXTRACT (0,2, COMMAND) 

$ IF COMMAND . EQS. "EX" THEN GOTO END_LOOP 


$ GOTO GET_COMMAND 
$END_LOOP : 

$ ! EXAMPLE 2 

$ ! 

$GET_COMMAND : 

$ INQUIRE COMMAND- 

"Command (EXIT, DIRECTORY, TYPE, PURGE, DELETE, COPY) " 
$ COMMAND = F$EXTRACT (0,2, COMMAND) 


$ IF COMMAND .NES. "EX" THEN GOTO GET_COMMAND 
$ ! End of loop 

To perform a loop a specific number of times, use a counter as the termination 
variable. In the following example, 10 file names are input by the user and placed 
into the local symbols FI LI, FI L2, . . . , FI L10: 

$ NUM = 1 ! Set counter 

$LOOP: ! Begin loop 

$ INQUIRE FIL'NUM' "File" ! Get file name 

$ NUM = NUM + 1 ! Update counter 

$ IF NUM .LT. 11 THEN GOTO LOOP ! Test for termination 
$END_LOOP: ! End loop 


To perform a loop for a known sequence of values, use F$ELEMENT. In the 
following example, the files CH API, CH AP2, CH AP3, CHAPA, CHAPB, and 
CHAPC are processed in order: 

$ FILE_LIST = "1, 2, 3, A, B, C" 

$ INDEX = 0 
$PROCESS : 

$ NUM = F$ELEMENT (INDEX, ", \FILE_LIST) 

$ IF NUM .EQS. THEN GOTO END_LOOP 
$ FILE = "CHAP" NUM'" 

$ ! process file named by FILE 


$ INDEX = INDEX + 1 
$ GOTO PROCESS 
$END_LOOP : 

$ EXIT 

The following examples show different ways you can write loops. The first 
example tests the termination variable at the beginning of the loop. The loop 
terminates when the value of the symbol FILE is the null string. 
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$ LOOP: 

$ INQUIRE FILE "File (press Return to quit)" 
$ IF FILE . EQS. "" THEN GOTO DONE 
$ ! Process file 


S GOTO LOOP 
$ ! 

$ DONE: 


I n this example, the I NQUI RE command requests a file name. If the response is 
a null value (for example, if you press Ctrl/Z or the Return key) the loop does not 
execute. Otherwise, the loop executes repeatedly until you enter a null value. 

The next example uses a counter to control the number of times a loop executes. 

I n this example, the loop executes 10 times; the termination variable is tested at 
the end of the loop. 

$! Obtain 10 file names and store them in the 
$ ! symbols FILEJL to FILE_10 

SI 

$ COUNT = 0 
$ LOOP: 

$ COUNT = COUNT + 1 

$ INQUIRE FILE_' COUNT' "File" 

$ IF COUNT . LT . 10 THEN GOTO LOOP 
S! 

$ PROCESS_FILES : 


This example uses the symbol COUNT to record the number of times the 
commands in the loop are executed. The example also uses COUNT to create the 
symbol names F I L E_l, F I L E_2, and so on to F I L E_10. N ote that the val ue of 
COUNT is incremented at the beginning of the loop but is tested at the end of 
the loop. Therefore, when COUNT is incremented from 9 to 10, the loop executes 
a last time (obtaining a value for FI LE_10) before the I F statement finds a false 
result. 

To perform a loop for a known sequence of values, use the F$ELEMENT lexical 
function. The F$ELEMENT function obtains items from a list of items separated 
by delimiters. You must supply the item number, the item delimiter, and the list 
as arguments for F$ELEMENT. For example: 

$ FILE_LIST = " CHAP 1 / CHAP 2 / CHAP 3 / CHAP 4 / CHAP 5 " 

$ NUM = 0 
$ ! 

$! Process each file listed in FILE_LIST 
$ PR0CESS_L00P : 

$ FILE = F$ELEMENT (NUM, " / " , FILE_LIST) 

$ IF FILE .EQS. "/" THEN GOTO DONE 
$ COPY 'FILE' .MEM MORRIS ::DISK3: [DOCSET]*.* 

$ NUM = NUM + 1 

$ GOTO PROCESS_LOOP 

$ ! 

$ DONE: 

$ WRITE SYS$OUTPUT "Finished copying files." 

$ EXIT 


15-47 


Command Procedures: Programming with DCL 

15.6 Techniques for Controlling Execution Flow 

This command procedure uses a loop to copy the files listed in the symbol FI LE_ 
LI ST to a directory on another node. The first file returned by the F$ELEMENT 
function is CHAP1, the next file is CHAP2, and soon. Each time through the 
loop, the value of NUM is increased so that the next file name is obtained. When 
the F$ELEMENT returns a slash, all the items from FILE_LIST have been 
processed and the loop is terminated. 

For more information on how to use F$ELEMENT, see the OpenVMS DCL 
Dictionary. 

15.6.6 Writing Case Statements 

A case statement is a special form of conditional code that executes one out of 
a set of command blocks, depending on the value of a variable or expression. 
Typically, the valid values for the case statement are labels at the beginning of 
each command block. The case statement passes control to the appropriate block 
of code by using the specified value as the target label in a GOTO statement. 

To write a case statement: 

1. List the labels. 

Equate a symbol to a string that contains a list of the labels delimited by 
slashes (or any character you choose to act as a delimiter). This symbol 
definition should precede the command blocks. 

S COMMAND_LIST = "/PURGE/DELETE/EXIT/" 

2. Write the case statement. 

First, use the I NQUI RE command to get the value of the case variable. 

Next, use the IF command with F$LOCATE and F$LENGTH to determine 
whether the value of the case variable is valid. If the case variable is valid, 
execute the case statement (with a GOTO command) to pass control to the 
appropriate block of code. Otherwise, display a message and exit or request a 
different case value. 

I n the following example, the label is equated to the full command name. 
Therefore, F$LOCATE includes the delimiters in its search for the command 
name to ensure that the command is not abbreviated. 

$GET_COMMAND : 

S INQUIRE COMMAND - 

"Command (EXIT, PURGE, DELETE) " 

$ IF F$L0CATE ( " / " +C0MMAND+ " / " , COMMAND_LIST ) .EQ. - 
F$LENGTH (COMMAND_LIST) THEN GOTO ERR0R_1 
S GOTO 'COMMAND' 


$ERR0R_1 : 

S WRITE SYS$OUTPUT "No such command as "COMMAND'." 

S GOTO GET_COMMAND 

3. Write the command blocks. 

Each block of commands may contain one or more commands. Begin each 
command block with a unique label. End each command block by passing 
control to a label outside the list of command blocks. 
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$GET_COMMAND : 


$PURGE : 

$ INQUIRE FILE 
$ PURGE 'FILE' 

$ GOTO GET_COMMAND 
$ ! 

$DELETE : 

$ INQUIRE FILE 
$ DELETE 'FILE' 

$ GOTO GET_COMMAND 
$ ! 

SEXIT: 

As another example, the following procedure verifies that a command is valid 
at the beginning of the procedure. If the command is valid, then the procedure 
executes the command. Note that the labels that identify each command block are 
the same as the commands in the option list. This allows you to use the symbol 
COMMAND (which is equated to the user's request) in the GOTO statement. 

$ COMMAND_LIST = "DELETE/DIRECTORY/EXIT/" + - 
"PRINT/PURGE/TYPE/" 

$ ! 

$ GET_C0MMAND_L00P : 

$ INQUIRE COMMAND - 

"Enter command (DELETE, DIRECTORY, EXIT, PRINT, PURGE, TYPE)" 

$ IF F$LOCATE (COMMAND+"/" , COMMAND_LIST) . EQ. - 

F$LENGTH (COMMAND_LIST) THEN GOTO ERROR 
$ GOTO 'COMMAND' 

$! 

$ (Execute if user entered DELETE 
$ DELETE: 

$ WRITE SYS$OUTPUT "This is the DELETE section." 


$ GOTO GE T_C0MMAND_L00P 

$ ! 

$ (Execute if user entered DIRECTORY 
$ DIRECTORY: 

$ WRITE SYS$OUTPUT "This is the DIRECTORY section. 


$ GOTO GE T_C0MMAND_L00P 


$ ! 

$ EXIT: 

$ WRITE SYS$OUTPUT "Directory ' ' F$DIRECTORY () ' has been cleaned." 
$ EXIT 
$ ! 

$! Error section 
$ ERROR: 

$ WRITE SYS$OUTPUT "You entered an invalid command." 

$ GOTO GE T_C0MMAND_L00P 
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15.6.7 Using the EXIT Command 

You can use the EXIT command to ensure that a procedure does not execute 
certain lines. For example, if you write an error-handling routine at the end of a 
procedure, place an EXIT command before the routine, as follows: 


$ EXIT ! End of normal execution path 

$ ERR0R_R0UTINE: 


The EXIT command is also useful for writing procedures that have more than one 
execution path. For example: 

$ START: 

$ IF PI . EQS . "TAPE" .OR. PI ,EQS. "DISK" THEN GOTO 'PI' 

$ INQUIRE PI "Enter device (TAPE or DISK) " 

$ GOTO START 

$ TAPE: ! Process tape files 


$ EXIT 

$ DISK: ! Process disk files 


$ EXIT 

This command procedure requires either TAPE or DISK as a parameter (PI). 
When you execute the procedure, the I F command uses a logical .OR. to test 
whether you entered either of these strings. If one of the required parameters 
is present, the GOTO command branches appropriately by using the parameter 
as the branch label. If neither parameter was present (that is, if PI was neither 
TAPE nor DISK), the INQUIRE command prompts for a correct parameter. The 
GOTO START command establishes a loop. 

The commands following each of the labels— TAPE and DISK— provide different 
paths through the procedure. The EXIT command before the DISK label ensures 
that the commands after the DISK label do not execute unless the procedure 
branches explicitly to the label. 

Note that the EXIT command at the end of the procedure is not required because 
the end-of-file of the procedure causes an implicit EXIT command. However, 
using the EXIT command is recommended. 

15.6.8 Using the STOP Command 

You can use the STOP command in a command procedure or batch job to ensure 
that all procedure levels are terminated if a severe error occurs. For example: 

$ ON SEVERE_ERROR THEN STOP 


If you include this line in a command procedure and a severe error occurs, 
the command procedure terminates. I n a command procedure that is executed 
interactively, control is returned to command level 0. In a batch job, the job 
terminates. 
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15.7 Controlling Error Conditions and Ctrl/Y Interruptions 

The following table describes the default action taken when an error condition 
or a Ctrl/Y interruption occurs while a command procedure is executing. 

You can override these default actions with the ON, SET [NO]ON, and SET 
[NO]CONTROL=Y commands. When reading this table, remember that command 
level 0 is the highest command level and command level 31 is the lowest 
command level. 


Interrupt 


Default Action 


E rror or severe error 


Procedure exits to the next command level. 


Ctrl/Y at DCL command level Procedure is interrupted: procedure can continue if no 
or command level 1 other image forces it to exit. 


Ctrl/Y at command level Procedure exits to the next higher command level, 

lower than level 1 


15.7.1 Detecting Errors in Command Procedures 

When each DCL command in a command procedure completes execution, the 
command interpreter saves a condition code that describes the reason why the 
command terminated. This code can indicate successful completion or it can 
identify an informational or error message. 

The command interpreter examines the condition code after it performs each 
command in a command procedure. If an error that requires special action has 
occurred, the system performs the action. Otherwise, the next command in the 
procedure executes. 

15.7.1.1 Displaying Condition Codes ($STATUS) 

The command interpreter saves the condition code as a 32-bit longword in the 
reserved global symbol $STATUS. The $STATUS symbol conforms to the format 
of a system message code as follows: 

• Bits 0-2 contain the severity level of the message. 

• Bits 3-15 contain the message number. 

• Bits 16-27 contain the number associated with the facility that generated the 
message. 

• Bits 28-31 contain internal control flags. 

When a command completes successfully, $STATUS has an odd value. (Bits 0-2 
contain a 1 or a 3.) When any type of warning or error occurs, $STATUS has an 
even value. (Bits 0-2 contain a 0, 2, or 4.) The command interpreter maintains 
and displays the current hexadecimal value of $STATUS. You can display the 
ASCII translation of $STATUS by entering the SHOW SYMBOL $STATUS 
command. I n the following example, a file name is entered incorrectly: 

$ CREATE %FILE.LIS 

%CREATE-E-0PEN0UT, error opening %FRED.LIS; as output 
-RMS-F-WLD, invalid wildcard operation 
$ SHOW SYMBOL $STATUS 
$STATUS = " %X109110A2 " 

$ WRITE SYS$0UTPUT F$MESSAGE ( %X1 0911 0A2 ) 

%CREATE-E-0PEN0UT, error opening ! AS as output 
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15.7.1.2 Passing Status Values with the EXIT Command 

When a command procedure exits, the command interpreter returns the condition 
code for the previous command in $STATUS. The condition code provides 
information about whether the most recent command executed successfully. 

When you use the EXIT command in a command procedure, you can specify a 
value that overrides the value that DCL would have assigned to $STATUS. This 
value, called a status code, must be specified as an integer expression. 

When a command procedure contains nested procedures to create multiple 
command levels, you can use the EXIT command to return a value that explicitly 
overrides the default condition codes. 

For example, suppose the procedureA.COM contains the following lines: 

$ ! This is file A. COM 
$! 

$ @B 


The procedure B.COM contains the following lines: 

$ ! This is file B.COM 
$! 

$ ON WARNING THEN GOTO ERROR 


$ ERROR: 

$ EXIT 1 

The ON command means that if any warnings, errors, or severe errors occur 
when B.COM is executing, the procedure is directed to the label ERROR. Here, 
the condition code is explicitly set to 1, indicating success. Therefore, when 
B.COM terminates, it passes a success code back to A. COM regardless of whether 
an error occurred. 

15.7.1.3 Determining Severity Levels ($SEVERITY) 

The low-order three bits of $STATUS represent the severity of the condition that 
caused the command to terminate. This portion of the condition code is contained 
in the reserved global symbol $SEVERITY. The $SEVERITY symbol can have the 
values 0 to 4, with each value representing one of the following severity levels: 


Value 

Severity 

0 

Warning 

1 

Success 

2 

Error 

3 

1 nformation 

4 

Fatal (severe) error 


Note that the success and information codes have odd numeric values, and 
warning and error codes have even numeric values. You can test for the 
successful completion of a command with IF commands that perform logical 
tests on $SE VERITY or $STATUS as follows: 
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$ IF $SEVERITY THEN GOTO OKAY 
$ IF $STATUS THEN GOTO OKAY 

These IF commands branch to the label OKAY if $SEVERITY and $STATUS have 
true (odd) values. When the current value in $SEVERITY and $STATUS is odd, 
the command or program completed successfully. If the command or program did 
not complete successfully, then $SEVERITY and $STATUS are even; therefore, 
the I F expression is false. 

I nstead of testing whether a condition is true, you can test whether it is false. 

For example: 

S IF .NOT. $STATUS THEN . . . 

The command interpreter uses the severity level of a condition code to determine 
whether to take the action defined by the ON command as described in 
Section 15.7.2. 


15.7.1.4 Using Commands That Do Not Set $STATUS 

Most DCL commands invoke system utilities that generate status values and 
error messages when they complete. However, there are several commands 
that do not change the values of $STATUS and $SEVERITY if they complete 
successfully. These commands are as follows: 


CONTINUE 

EOD 

IF 

SHOW STATUS 
WAIT 


DECK 
EXAMINE 
RECALL 
SHOW SYMBOL 


DEPOSIT 

GOTO 

SET SYMBOL/SCOPE 
STOP 


If any of these commands result in a nonsuccessful status, the condition code is 
placed in $STATUS and the severity level is placed in $SEVERITY. 


15.7.2 Handling Error Conditions 

By default, the command interpreter executes an EXIT command when a 
command results in an error or severe error. This causes the procedure to exit 
to the previous command level. For other severity levels (success, warning, and 
informational) the command procedure continues. 

There is one exception to the way that the command interpreter handles errors. 

If you reference a label in a command procedure and the label does not exist (for 
example, if you include the command GOTO ERR1 and ERR1 is not used as a 
label in the procedure), the GOTO command issues a warning and the command 
procedure exits. 

When the system issues an EXIT command as part of an error-handling routine, 
it passes the value of $STATUS back to the previous command level, with one 
change. The command interpreter sets the high-order digit of $STATUS to 1 so 
that the command interpreter does not redisplay the message associated with the 
status value. 

For example, the following command procedureTEST.COM contains an error in 
the output file specification: 

$ CREATE DUMMY. DAT \ 

THIS IS A TEST FILE 
$ SHOW TIME 
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When you execute the procedure, the CREATE command returns an error in 
$STATUS and displays the corresponding message. The command interpreter 
then examines the value of $STATUS, determines that an error occurred, issues 
an EXIT command, and returns the value of $STATUS. When the procedure 
exits, the error message is not redisplayed, because the CREATE command 
already displayed the message once. At DCL command level, you can see that 
$STATUS contains the error message but the high-order digit has been set to 1. 

$ 0TEST 

%CREATE-E-OPENOUT, error opening DUMMY.DAT as output 
-RMS-F-SYN, file specification syntax error 

%DCL-W-SKPDAT, image data (records not beginning with "$") ignored 
$ SHOW SYMBOL $STATUS 
$STATUS = "%X109110A2 " 

$ WRITE SYS$OUTPUT F$MESSAGE ( %X1 0 911 0A2 ) 

%CREATE-E-OPENOUT, error opening ! AS as output 

You can use the ON and SET [NO]ON commands to change the way that the 
system responds to errors in command procedures. For more information about 
the global symbols $STATUS and $SEVERITY, see Chapter 14. 

15.7.2.1 Using the ON Command 

The ON command specifies an action to be performed if an error of a certain 
severity or greater severity occurs. If such an error occurs, the system takes the 
following actions: 

• Performs the action specified by the ON command. 

• Sets $STATUS and $SEVERITY to indicate the result of the specified ON 
action. I n general, they are set to success. 

• Resets the default error action (to exit if an error or severe error occurs). 

The format of the ON command is as follows: 

ON condition THEN [$] command 

You can specify error conditions with one of the keywords WARNI NG, ERROR, or 
SEVERE_ERROR. If an ON command action is established for a specific severity 
level, the command interpreter performs the specified action when errors of 
the same or worse severity occur. When less severe errors occur, the command 
interpreter continues processing the file. Table 15-3 summarizes how the ON 
command controls error handling. 


Table 15-3 ON Command Keywords and Actions 


ON Keyword 

Action Taken 

WARNING 

Command procedure performs the specified action if a warning, 
error, or severe error occurs. 

ERROR 

Command procedure performs the specified action if an error or 
severe error occurs. The procedure continues if a warning occurs. 

SEVERE_ERROR 

Command procedure performs the specified action if a severe 
(fatal) error occurs. The procedure continues if a warning or error 


occurs. 


For example, if you want to override the default error handling so that a 
procedure exits when warnings, errors, or severe errors occur, use the following 
command: 
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$ ON WARNING THEN EXIT 

An ON command action is executed only once. Therefore, after a command 
procedure performs the action specified in an ON command, the default error 
action is reset. For example, suppose that your procedure includes the following 
command: 

$ ON ERROR THEN GOTO ERR1 

I n this case, the command procedure executes normally until an error or severe 
error occurs. If such an error occurs, then the procedure resumes executing at 
ERR1, $STATUS and $SEVERITY are set to success, and the default error action 
is reset. If a second error occurs before another ON or SET NOON command is 
executed, the procedure exits to the previous command level. 

The action specified by an ON command applies only within the command level 
in which the command is executed. Therefore, if you execute an ON command 
in a procedure that invokes another procedure, the ON command action does not 
apply to the nested procedure. 

Figure 15-1 illustrates ON command actions. In addition, the sample command 
proceduresFORTUSER.COM and CALC.COM in Appendix C illustrate the use of 
the ON command to establish error handling. 

Figure 15-1 ON Command Actions 


DBA1 :[HIGGINS]FORT.COM 



ZK-0826-GE 

1 This ON command overrides the default command action (on warning, 
continue; on error or severe error, exit). If an error or severe error occurs 
while A. FOR is being compiled, the command procedure continues with the 
next command. 

2 The default command action is reset if the previous ON command takes 
effect. Thus, if an error or severe error occurs while both A. FOR and B.FOR 
are being compiled, the command procedure exits. 

3 If a warning, error, or severe error occurs while C.FOR is being compiled, the 
command procedure exits. 


15-55 


Command Procedures: Programming with DCL 

15.7 Controlling Error Conditions and Ctrl/Y Interruptions 

4 If the command procedure does not exit before a command is executed, the 
command action takes effect. 

15.7.2.2 Disabling Error Checking 

You can prevent the command interpreter from checking the status returned from 
commands by using the SET NOON command in your command procedure, which 
sets the ON command to NO status. When you use the SET NOON command, 
the command interpreter continues to place values in $STATUS and $SEVERITY 
but does not perform any error checking. You can restore error checking with the 
SET ON command or with an ON command. For example: 

$ SET NOON 
$ RUN TESTA 
$ RUN TESTB 
$ SET ON 

The SET NOON command preceding the RUN commands ensures that the 
command procedure continues if either of the programs TESTA or TESTB return 
an error condition. The SET ON command restores the default error checking by 
the command interpreter. 

When a procedure disables error checking, it can explicitly check the value of 
$STATUS following the execution of a command or program. For example: 

$ SET NOON 
$ FORTRAN MYFILE 
$ IF $STATUS THEN LINK MYFILE 
$ IF $STATUS THEN RUN MYFILE 
$ SET ON 

In the previous example, the first IF command checks whether $STATUS has a 
true value (that is, if it is an odd numeric value). If so, the FORTRAN command 
was successful and the LINK command executes. After the LINK command 
executes, $STATUS is tested again. If $STATUS is odd, the RUN command 
executes; otherwise, the RUN command does not execute. The SET ON command 
restores the current ON condition action; that is, whatever condition was in effect 
before the SET NOON command was executed. 

The SET ON or SET NOON command applies only at the current command 
level; that is, the command level at which the command is executed. If you 
use the SET NOON command in a command procedure that calls another 
command procedure, the default error-checking mechanism will be in effect 
within the nested procedure. Note that SET NOON has no meaning when 
entered interactively at command level 0. 

15.7.2.3 Restarting Batch Jobs 

Chapter 17 describes how to reexecute your batch job if the system fails before 
the job is finished. By default, a batch job is reexecuted beginning with the first 
line. However, you can use the following symbols in your command procedure to 
specify a different restarting point: 

• $RE START 

A global symbol whose value is true if the batch job has been started at least 
once before this execution. Do not specify a value for $RE START; the system 
will assign the appropriate value. 

• BATCH $RE START 

A global symbol whose value you specify using the SET RESTART_VALUE 
command. 
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The following command procedure describes how to use the $RE START and the 
BATCH $RE START symbols: 

1. Begin each possible starting point of the procedure with a label. 

2. As the first step in each section, equate the value of BATCH $RE START to the 
label using the SET RESTART_VALUE command. 

3. At the beginning of the procedure, test $RE START. If $RE START is true, 
issue a GOTO statement using BATCH$RESTART as the transfer label. 

The following command procedure extracts a number of modules from a library, 
concatenates those modules, and then sorts the resulting file. If aborted, the 
command procedure reexecutes from the beginning of the file, from the statement 
labeled CONCATENATE_LI BRARI ES, or from the statement labeled SORT_ 
FILE, depending on the value of BATCH $RE START. (If you were extracting a 
number of separate modules, you could make each extraction a separate section.) 

$! SORT_MODDLES.COM 
$ ! 

$! Set default to the directory containing 
$! the library whose modules are to be sorted 
$ SET DEFAULT WORKDISK: [ACCOUNTS .DATA83] 

$ ! 

$! Check for restarting 
$ IF $ RESTART THEN GOTO "BATCH$RESTART " 

$ ! 

$ EXTRACT_LIBRARIES : 

$ SET REST ART_VALUE =EX T RAC T_L I B RAR I E S 


$ CONCATENATE_LIBRARIES : 

$ SET REST ART_VALUE =C ON CATENATE_LIBRARIES 


$ S0RT_FILE : 

$ SET RESTART_VALUE=SORT_FILE 


S EXIT 

15.7.3 Handling Ctrl/Y Interruptions 

By default, when you press Ctrl/Y while a command procedure is executing, the 
command interpreter prompts for command input at a special command level 
called Ctrl/Y command level. From Ctrl/Y command level, you can enter DCL 
commands that are executed within the command interpreter and then resume 
execution of the command procedure with the CONTINUE command. In addition, 
you can stop the procedure by entering a DCL command that forces the command 
procedure to stop executing. 

You can override the way that command procedures process Ctrl/Y interruptions 
by using the ON command as described in one of the following subsections. 

In the following command procedure, pressing Ctrl/Y while a file is being typed 
passes control to the label END_TYPE: 
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$! Type a file 

$ IF COMMAND .NES. "TY" THEN GOTO END_TYPE 
$ ON C0NTR0L_Y THEN GOTO END_TYPE 
$ TYPE 'FILESPEC' 

$END_TYPE : 

$! 

$! Reset default 
$ SET N0C0NTR0L=Y 
$ SET C0NTR0L=Y 


An ON CONTROL_Y command remains in effect until another ON CONTROL_Y 
or a SET NOCONTROL =Y command executes or the command procedure exits. 

To exit from a nonterminating loop when Ctrl/Y is disabled, you must delete 
your process from another terminal using the DCL command STOP. If you 
disable the default Ctrl/Y action, reset it as soon as possible. To reset the default 
Ctrl/Y action, execute the SET NOCONTROL=Y command followed by the SET 
CONTROL =Y command as shown in the previous example. 

15.7.3.1 Interrupting a Command Procedure 

You can interrupt a command procedure that is executing interactively by 
pressing Ctrl/Y. When you press Ctrl/Y, the command interpreter establishes 
a new command level, called the Ctrl/Y level, and prompts for command input. 
When the interruption occurs depends on the command or program that is 
executing: 

• If the command is executed by the command interpreter itself (for example, 

IF, GOTO, or an assignment statement), the command completes execution 
before the command interpreter prompts for a command at the Ctrl/Y level. 

• If the command or program is a separate image (that is, an image other than 
the command interpreter), the command is interrupted and the command 
interpreter prompts for a command at the Ctrl/Y level. 

At the Ctrl/Y level, the command interpreter stores the status of all previously 
established command levels so that it can restore the correct status after any 
Ctrl/Y interrupt. 

After you interrupt a procedure, you can do the following: 

• Enter a DCL command that is executed within the command interpreter. 
Among these commands are the SET VERI FY, SHOW Tl ME, SHOW 
TRANSLATION, ASSIGN, EXAMINE, DEPOSIT, SPAWN and ATTACH 
commands. After you enter one or more of these commands, you can 
resume the execution of the procedure with the CONTINUE command. 

See Table 15-2 for a complete list of commands that are executed within the 
command interpreter. 

When you enter the CONTI NUE command, the command procedure resumes 
execution with the interrupted command or program or with the line after the 
most recently completed command. 

• Enter a DCL command that executes another image. When you enter any 
command that invokes a new image, the command interpreter returns to 
command level 0 and executes the command. This terminates the command 


15-58 


Command Procedures: Programming with DCL 
15.7 Controlling Error Conditions and Ctrl/Y Interruptions 

procedure's execution. Any exit handlers declared by the interrupted image 
are allowed to execute before the new image is started. 

• Enter the EXIT or STOP command to terminate the command procedure's 
execution. If you use the EXIT command, exit handlers declared by the 
interrupted image are allowed to execute. However, the STOP command does 
not execute these routines. 


Note 

If you do not exit from a command procedure (either explicitly from 
the command level or as part of an ON routine) following a Ctrl/Y, the 
next command you enter is interpreted in the context of the command 
procedure. For example, suppose you define the following symbol at the 
interactive level: 

$ MAIL = "mail/edit= (send, reply, forward) " 

If you enter Ctrl/Y to interrupt a command procedure that does not 
include this definition and then enter the command MAIL to send a 
message, your editor is not invoked automatically. 


If you interrupt the execution of a privileged image, you can enter only the 
CONTI NUE, SPAWN, or ATTACH commands if you want to save the context of 
the image. If you enter any other commands (except from within a subprocess 
that you have spawned or attached to), the privileged image is forced to exit. 

15.7.3.2 Setting a Ctrl/Y Action Routine 

The ON command, which defines an action to be taken in case of error conditions, 
also provides a way to define an action routine for a Ctrl/Y interruption that 
occurs during execution of a command procedure. The action that you specify 
overrides the default Ctrl/Y action (that is, to prompt for command input at the 
Ctrl/Y command level). For example: 

$ ON C0NTR0L_Y THEN EXIT 

If a procedure executes this ON command, a subsequent Ctrl/Y interruption 
during the execution of the procedure causes the procedure to exit. Control is 
passed to the previous command level. 

When you press Ctrl/Y to interrupt a procedure that uses ON CONTROL_Y, the 
following actions are taken: 

• If the command currently executing is a command executed within the 
command interpreter, the command completes and the Ctrl/Y action is taken. 

• If the current command or program is executed by an image other than the 
command interpreter, the image is forced to exit and the Ctrl/Y action is 
taken. If the image has declared an exit handler, however, the exit handler 
is executed before the Ctrl/Y action is taken. The image cannot be continued 
following the Ctrl/Y action. 

The execution of a Ctrl/Y action does not automatically reset the default Ctrl/Y 
action (that is, to prompt for command input at the Ctrl/Y command level). A 
Ctrl/Y action remains in effect until one of the following conditions occurs: 

• The procedure terminates (as a result of pressing Ctrl/Y, executing an EXIT 
or STOP command, or a default error condition handling action). 
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• Another ON CONTROL_Y command is executed. 

• The procedure executes the SET NOCONTROL =Y command (see 
Section 15.7.3.3). 

For example, a procedure can contain the following line: 

$ ON C0NTR0L_Y THEN SHOW TIME 

When this procedure executes, each Ctrl/Y interruption results in the execution 
of the SH OW TIME command. After each SH OW TIME command executes, the 
procedure resumes execution at the command following the command that was 
interrupted. 

Figure 15-2 illustrates two ON CONTROL_Y commands and describes the flow of 
execution following Ctrl/Y interruptions. 


Figure 15-2 Flow of Execution Following Ctrl/Y Action 


$ 0FILES 


Ctrl/Y | 0 


$ 


DBA1 :[HIGGINS]FILES.COM 


$ ON CONTROL_Y THEN GOTO CLEANJJP 


$ TYPE STATUS. OUT; 1 

$ IF $ STATUS THEN DELETE STATUS. OUT ;1 



$ DELETE STATUS. OUT ;1 
$ DELETE * . TMP ; * 

$ EXIT Q 


DBA1 :[HIGGINS] PRIV.COM 



$ ON CONTROL_Y THEN WRITE SYS$OUTPUT- 


"Interruption not allowed. .. continuing" 

1 Ctrl/Y 1 O 

$ TYPE STATUS. OUT; 1 4% 

0 

$ IF $STATUS THEN DELETE STATUS. OUT; 1 ™ 

Interruption not allowed. .. continuing 
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1 The Ctrl/Y interruption occurs during the execution of the TYPE command. 

2 Control is then transferred to the label CLEAN UP. 

3 After executing the routine, the command procedure exits, and returns to the 
interactive command level. 

4 The Ctrl/Y interruption occurs during the execution of the TYPE command. 

5 The WRITE command specified in the ON command is executed. 
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6 The command procedure continues execution at the command following the 
interrupted command. 

A Ctrl/Y action can be specified in each active command level and affects only 
the command level in which it is specified. Figure 15-3 illustrates what happens 
when Ctrl/Y is pressed during the execution of a nested command procedure. 

Figure 15-3 Default Ctrl/Y Action for Nested Procedures 

$ @ SEARCH 


DBA1 :[HIGGINS] SUBSEARCH.COM 


| Ctrl/Y | 0 


DBA1 :[HIGGINS] SUBSUB.COM 


| Ctrl/Y | 0 


$ ON CONTROL_Y THEN SHOW TIME 

$ EXIT 


$ @ SUBSUB 


| Ctrl/Y | 0 


DBA1 :[HIGGINS]SEARCH.COM 


$ ON CONTROL_Y THEN GOTO CLEAN_UP 


$ @ SUBSEARCH 
$ NEXT_STEP : o 


$ EXIT 
$ CLEAN_UP: 
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1 If a Ctrl/Y interruption occurs while SEARCH.COM is executing, control is 
transferred to the label CLEAN_UP. 

2 If a Ctrl/Y interruption occurswhileSUBSEARCH.COM is executing, control 
is transferred to the label NEXT_STEP in SEARCH.COM. 

3 Because no Ctrl/Y action is specified in SUBSEARCH.COM, the procedure 
exits to the previous command level when a Ctrl/Y interruption occurs. 

4 If a Ctrl/Y interruption occurs while SUBSUB.COM is executing, the SHOW 
Tl ME is executed. 
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15.7.3.3 Disabling and Enabling Ctrl/Y Interruptions 

The SET NOCONTROL=Y command disables Ctrl/Y handling. That is, if a 
command procedure executes the SET NOCONTROL=Y command, pressing 
Ctrl/Y has no effect. 

The SET NOCONTROL=Y command also cancels the current Ctrl/Y action 
established with the ON CONTROL_Y command. To reestablish the default 
Ctrl/Y action, use the following two commands: 

$ SET N0C0NTR0L=Y 
$ SET C0NTR0L=Y 

The first command disables Ctrl/Y handling and cancels the current ON 
CONTROL_Y action; the second command enables Ctrl/Y handling. At this 
point, the default action is reinstated. That is, if Ctrl/Y is pressed during the 
execution of the procedure, the command interpreter prompts for a command at 
the Ctrl/Y command level. 

You can use the SET NOCONTROL =Y command at any command level. It affects 
all command levels until the SET CONTROL=Y command reenables Ctrl/Y 
handling. 


Note 

The ON CONTROL_Y and SET NOCONTROL=Y commands are intended 
for special applications. Digital does not recommend, in general, that you 
disable Ctrl/Y interruptions. To exit from a nonterminating loop when 
Ctrl/Y is disabled, you must delete (from another terminal) the process 
from which the looping procedure is executing. 


15.8 Designing Command Procedures 

Before writing a command procedure, perform the tasks interactively that the 
command procedure will execute. As you type the necessary commands, note the 
following: 

• Variables 

Data that changes each time you perform the task. 

• Conditionals 

Conditions (for example, any command or set of commands) that can vary 
and, therefore, must be tested each time you perform the task. Note the 
commands and the conditions under which you would execute them. 

• Iteration 

Any command or set of commands that is performed repetitively until a 
condition is met. Note the commands and the factors that control how often 
you repeat them. 

The following illustration shows the commands needed to clean up a directory: 
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Command Variable 


Condition 


Repeat 

Until 

Done 


▼ 


DIRECTORY ► 

or 

TYPE filespec ► 

or 

PURGE filespec ► 

or 

DELETE filespec ► 

or 

COPY filespec new-filespec ► 


To display new filespec 
To display a file 
To purge a file 
To delete a file 
To copy a file 
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If you create or delete files in your directory, the file names will be different 
each time you clean your directory; therefore, file names are variables. Any or 
all of the commands might be executed depending on the operation you need to 
perform; therefore, each command is conditional. The entire process is repeated 
until the directory is clean; therefore, it is iterative. 

You must decide how to load the variables, test the conditionals, and exit from 
the loop. For the directory-cleaning procedure, a programmer made the following 
design decisions: 

• Load variables 

The command procedure gets the file names from the terminal. 

• Test conditionals 

The command procedure gets a command name from the terminal and 
executes the appropriate statements based on the command name. The 
first two characters of each command must be read to differentiate between 
DELETE and DIRECTORY. 

• Exit from loop 

You must enter the EXIT command to exit from the loop. 

Figure 15-4 shows the steps for completing the design. 


15-63 


Command Procedures: Programming with DCL 
15.8 Designing Command Procedures 


Figure 15-4 Steps for Completing Command Procedure Design 

' l 

GET command 


If command begins with Dl 
DIRECTORY 


If command begins with TY 
GET filespec 
TYPE filespec 


If command begins with PU 
GET filespec 
PURGE filespec 


If command begins with DE 
GET filespec 

DELETE/CONFIRM filespec 


If command begins with CO 
GET filespec 
GET new-filespec 
COPY filespec new-filespec 


If command begins with EX 
EXIT 
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To make a command procedure easier to understand and maintain, write the 
statements so that the procedure executes from the first command to the last 
command. The following sections show the steps you can use to code a command 
procedure to clean up a directory (CLEAN.COM). 

Assigning Values to Variables 

To assign values to variables in a command procedure, you can use one or more 
of the methods for obtaining input described in Section 15.4.1. Alternatively, you 
can use the I NQU I RE command to equate the values to symbols. The following 
command procedure prompts the user for a command name and equates the value 
to the symbol COMMAND: 

$ INQUIRE COMMAND - 

"Enter command (DELETE, DIRECTORY, PRINT, PURGE, TYPE) " 

According to your design, the first thing you want to do after you prompt for a 
command is to see whether you are done or whether you need to execute the 
command. By adding an EXIT command to the previous example, you can test 
whether the user entered "EXIT". For example: 
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$ INQUIRE COMMAND - 

"Enter command (DELETE, DIRECTORY, EXIT, PRINT, PURGE, TYPE)" 

$ IF COMMAND . EQS. "EXIT" THEN EXIT 

Next, you need to determine which command to execute. To do this, check the 
command entered by the user against each possible command. If you find a 
match, execute the command. If you do not find a match, go on to the next 
command. If there is no match after you have checked for each valid command, 
output an error message. 

To test whether a condition is true, use the I F...THEN commands. To change the 
flow of execution, use the GOTO command to direct the flow of execution to a 
label in the command procedure. I n addition, use program stubs as placeholders 
for the code that performs each command. A program stub is a temporary 
section of code that you use in your procedure while you test the design. Usually, 
a program stub outputs a message stating the function it is replacing. After the 
overall design works correctly, replace each program stub with the correct code. 
For example: 

$ INQUIRE COMMAND - 

"Enter command (DELETE, DIRECTORY, EXIT, PRINT, PURGE, TYPE)" 

$ IF COMMAND .EQS. "EXIT" THEN EXIT 

$ ! 

$ (Execute if user entered DELETE 
$ DELETE: 

$ IF COMMAND .NES. "DELETE" THEN GOTO DIRECTORY 

$ WRITE SYS$OUTPUT "This is the DELETE section." 

S! 

$! Execute if user entered DIRECTORY 
$ DIRECTORY: 

$ IF COMMAND .NES. "DIRECTORY" THEN GOTO PRINT 

$ WRITE SYS$OUTPUT "This is the DIRECTORY section." 

$ ! 

$ (Execute if user entered PRINT 
$ PRINT: 

$ IF COMMAND .NES. "PRINT" THEN GOTO PURGE 

$ WRITE SYS$OUTPUT "This is the PRINT section." 

$ ! 

$ (Execute if user entered PURGE 
$ PURGE: 

$ IF COMMAND .NES. "PURGE" THEN GOTO TYPE 

$ WRITE SYS$OUTPUT "This is the PURGE section." 

$ ! 

$ (Execute if user entered TYPE 
$ TYPE: 

$ IF COMMAND .NES. "TYPE" THEN GOTO ERROR 

$ WRITE SYS$OUTPUT "This is the TYPE section." 

S! 

$ ERROR: 

$ WRITE SYS$OUTPUT "You entered an invalid command." 

$ 

$ EXIT 

Adding Loops 

Now that you have the lines that test your conditionals, finish the design by 
adding the loop that allows you to obtain a command, process the command, 
and repeat the process until the user enters the EXIT command. To do this, 
direct the flow of execution back to the beginning of the procedure after the 
procedure executes a command. Leave the loop only when the user enters the 
EXIT command. For example: 
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$ GET_C0MMAND_L00P : 

$ INQUIRE COMMAND - 

"Enter command (DELETE, DIRECTORY, EXIT, PRINT, PURGE, TYPE) " 

$ IF COMMAND . EQS. "EXIT" THEN GOTO END_L00P 

$! 

$! Execute if user entered DELETE 
$ DELETE: 

$ IF COMMAND .NES. "DELETE" THEN GOTO DIRECTORY 

$ WRITE SYS$OUTPUT "This is the DELETE section." 

$ GOTO GET_COMMAND_LOOP 

$! 

$ (Execute if user entered DIRECTORY 
$ DIRECTORY: 

$ IF COMMAND .NES. "DIRECTORY" THEN GOTO PRINT 

$ WRITE SYS$OUTPUT "This is the DIRECTORY section." 

$ GOTO GET_COMMAND_LOOP 

$! 

$! Execute if user entered PRINT 
$ PRINT: 

$ IF COMMAND .NES. "PRINT" THEN GOTO PURGE 

$ WRITE SYS$OUTPUT "This is the PRINT section." 

$ GOTO GET_COMMAND_LOOP 

$ ! 

$! Execute if user entered PURGE 
$ PURGE : 

$ IF COMMAND .NES. "PURGE" THEN GOTO TYPE 

$ WRITE SYS$OUTPUT "This is the PURGE section." 

$ GOTO GET_COMMAND_LOOP 

$! 

$! Execute if user entered TYPE 
$ TYPE: 

$ IF COMMAND .NES. "TYPE" THEN GOTO ERROR 

$ WRITE SYS$OUTPUT "This is the TYPE section." 

$ GOTO GET_COMMAND_LOOP 

$ ! 

$ ERROR: 

$ WRITE SYS$OUTPUT "You entered an invalid command." 

$ GOTO GET_COMMAND_LOOP 

$ ! 

$ END_LOOP : 

$ WRITE SYS$OUTPUT "Directory "F$DIRECTORY () ' has been cleaned." 

$ EXIT 

Testing the Program Logic 

Once you have written the code using program stubs, test the overall logic of the 
command procedure. Test all possible paths of execution. To test CLEAN.COM, 
enter each valid command, enter an invalid command, and exit using the EXIT 
command. For example: 

$ @ CLEAN 

Enter command (DELETE, DIRECTORY, EXIT, PRINT, PURGE, TYPE) : DELETE 
This is the DELETE section. 


Enter command (DELETE, DIRECTORY, EXIT, PRINT, PURGE, TYPE) : EXIT 

Use the SET VERI FY and SFIOW SYM BOL commands to help debug command 
procedures. When verification is set, you can see errors and the lines that 
generate them. For example, the following section of CLEAN.COM contains a 
spelling error. You can determine where the error occurs by turning verification 
on before you execute the procedure. 
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$ SET VERIFY 
$ @ CLEAN 

$ GET_C0MMAND_L00P : 

$ INQUIRE COMMAND - 

"Enter command (DELETE, DIRECTORY, EXIT, PRINT, PURGE, TYPE)" 

Enter command (DELETE, DIRECTORY, EXIT, PRINT, PURGE, TYPE) : EXIT 
$ IF COMMAND . EQS. "EXIT" THEN GOTO END_LOP 

%DCL-W-USGOTO, target of GOTO not found - check spelling and presence of label 

The label END_LOP is spelled incorrectly. To correct the error, change the label 
to END_LOOP. 

The next example uses the SHOW SYMBOL command to determine how the 
symbol COMMAND is defined. 

$ SET VERIFY 
$ @ CLEAN 

$ GET_C0MMAND_L00P : 

$ INQUIRE COMMAND - 

"ENTER COMMAND (DELETE, DIRECTORY, EXIT, PRINT, PURGE, TYPE)" 

ENTER COMMAND (DELETE, DIRECTORY, EXIT, PRINT, PURGE, TYPE) : EXIT 
$ SHOW SYMBOL COMMAND 
COMMAND = "EXIT" 

$ IF COMMAND .EQS. "exit" THEN GOTO END_LOOP 


In this example, the SHOW SYMBOL command shows that the symbol 
COMMAND has the value "EXIT". The INQUIRE command automatically 
converts input to uppercase. The I F statement that tests the command uses 
lowercase characters in the string "exit", so DCL determines that the strings are 
not equal. To correct the error, make sure the quoted string in the I F statement 
is written in capital letters. The rest of the string can use either uppercase or 
lowercase. For example: 


$ if command ,eqs. "EXIT" then goto end_loop 


Replacing Program Stubs with Commands 

When your general design works correctly, complete the command procedure 
by substituting commands for the program stubs. After you replace a program 
stub with commands, test it to make sure the procedure works correctly. For a 
complicated task, it might be helpful to test the commands before adding them to 
the procedure. 

The following example shows the code for the TYPE section of CLEAN .COM : 

$! Execute if user entered TYPE 
$ TYPE: 

$ IF COMMAND ,NES. "TYPE" THEN GOTO ERROR 

$ INQUIRE FILE "File to type" 

$ TYPE 'FILE' 

$ GOTO GET_C0MMAND_L00P 
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Testing the Procedure 

Typically, command procedures need to be tested then debugged. For lengthy 
or complex command procedures, write the logic for the main procedure but use 
program stubs for the nested procedures and subroutine-type pieces of code. For 
example, the following program stub replaces the purge routine: 


$ ! Purge a file 

$ IF COMMAND .NES. "PU" THEN GOTO END_PURGE 
$ WRITE SYS$OUTPUT "Purge routine" ! program stub 
$END_PURGE : 


If you have a number of places that need program stubs, you can use one nested 
command procedure to insert the program stub logic as follows. (The command 
procedure STUB.COM would be in a separate file. It is shown indented here for 
clarity.) 


$ ! Purge a file 

$ IF COMMAND .NES. "PU" THEN GOTO END_PURGE 
$ 0STUB "Purge" 

$ ! STUB.COM 

$ ! Procedure STUB 

$ WRITE SYS$OUTPUT "''PI' routine" 

$END_PURGE : 


Once you have written the code using program stubs, you can test the overall 
logic of the command procedure as follows. Test all possible paths of execution. 


$ ! CLEAN.COM 

$ ! 

$GET_COMMAND : 

$ ! Read a command from the terminal 
$ INQUIRE COMMAND- 

"Command (EXIT, DIRECTORY, TYPE, PURGE, DELETE, COPY) " 
$ COMMAND = F$EXTRACT (0,2, COMMAND) 

$ ! 

$ IF COMMAND . EQS. "EX" THEN GOTO END_COMMAND 

$ ! 


$ ! Purge a file 

$ IF COMMAND .NES. "PU" THEN GOTO END_PURGE 
$ WRITE SYS$OUTPUT "Purge routine." 

$END_PURGE : 

$ ! 

$ ! Delete a file 

$ IF COMMAND .NES. "DE" THEN GOTO END_COMMAND 
$ WRITE SYS$OUTPUT "Delete routine." 

$ END_DELETE : 


$ GOTO GET_COMMAND 
$END_COMMAND : 
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Once the overall logic of the procedure works, you can begin filling in the program 
stubs. Fill in the first program stub, test it, and debug it if necessary. When that 
program stub works, move to the next one. 

Cleaning Up 

In general, execution of a command procedure should not change the user's 
process state. Therefore, a command procedure should include a set of commands 
that returns the process to its original state. Common cleanup operations include 
the following: 

• Closing files 

If you have opened any files, make sure that they are closed before the 
command procedure exits. You can use the lexical function F$GETJ PI to 
examine the remaining open file quota (FI LCNT) for the process. If FI LCNT 
is the same at the beginning and end of the command procedure, you know 
that no files have been left open. For example, the following lines display a 
warning message if a file is left open: 

$ FILJSOUNT = F$GETJPI ("", "FILCNT") 


$ IF FIL_COUNT .NE. F$GETJPI "FILCNT" ) THEN- 
WRITE SYS$OUTPUT "WARNING — file left open" 

• Deleting temporary or extraneous files 

If you have created temporary files, delete them. I n general, if you have 
updated any files, you should purge them to delete the previous copies. 
Before you delete files you have not created, make sure you want to delete 
them. For example, if you have updated a file that contains crucial data, you 
might want to make the purging operation optional. 

• Resetting default device and directory 

If you change the default device, the directory, or both, reset the original 
defaults before the command procedure exits. 

To save the name of the original default directory, use the DEFAULT keyword 
of the F$ENVI RONMENT lexical function. At the end of the command 
procedure, include a SET DEFAULT command that restores the saved device 
and directory. 

The following example saves and restores device and directory defaults: 

$ SAVJDEFAULT = F$ENVIRONMENT ( "DEFAULT" ) 


$ SET DEFAULT ' SAV_DEFAULT' 

The following table lists other commonly changed process characteristics as well 
as the lexical functions and commands used to save and restore the original 
settings. 
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Characteristic 

Lexical Function 

Used to Save 

Lexical Function 

Used to Restore 

DCL prompt 

F$ENVIRONMENT 

SET PROMPT 

Default protection 

F$ENVIRONMENT 

SET PROTECTION/DEFAULT 

Privileges 

F$SETPRV 

F $SETPRV or SET PROCESS 
/PRIVILEGES 

Control characters 

F$ENVIRONMENT 

SET CONTROL 

Verification 

F$VERIFY 

F$VERIFY 

M essage format 

F$ENVIRONMENT 

SET MESSAGE 

Key state 

F$ENVIRONMENT 

SET KEY 


For complete descriptions of these lexical functions, see the OpenVMS DCL 
Dictionary. 

To ensure that cleanup operations are performed even if the command procedure 
is aborted, begin each command level in the command procedure with the 
following statement: 

$ ON C0NTR0L_Y THEN GOTO CLEANJJP 

In each command level of the command procedure, place cleanup operations after 
the CLEAN_UP label. 

15.9 Writing a Login Command Procedure 

Each time you log in, the system automatically executes a command procedure, 
called a login command procedure (if one exists). The system also executes this 
procedure at the beginning of every batch job you submit. The system executes 
two types of login command procedures: 

• A systemwide (or group-defined) login command procedure 

• Your personal login command procedure 

These login procedures are described in the following sections. 

15.9.1 A Systemwide or Group-Defined Login Command Procedure 

If a systemwide (or group-defined) login command procedure exists, it is 
executed before your personal login command procedure. When the system 
login command procedure terminates, it passes control to your personal login 
command procedure. Systemwide and group-defined login command procedures 
allow your system manager to make sure that certain commands are always 
executed when you log in. 

To establish a system or group login command procedure, your system manager 
equates the logical name SYS$SYLOGIN to the appropriate login command 
procedure. Your system manager can specify that this login command procedure 
be used for all system users or for a certain group of users. 

15.9.2 Your Personal Login Command Procedure 

You can create a personal login command procedure to execute the same 
commands each time you log in. Name your login command procedure 
LOGIN.COM and place it in your top-level directory, unless your system manager 
tells you otherwise. 
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The following sample LOGIN.COM procedure illustrates some commands you 
might want to include in your login command procedure: 


Sample LOGIN.COM for user MARCIA with 
default disk of DISK3 

Exit if this is a batch job or another 
type of noninteractive process 

IF F$M0DE() .NES. "INTERACTIVE" THEN EXIT 1 

Define global symbols to tailor DCL commands 


PUR*GE 

SUB*MIT 

M*AIL 

DIRECTORY 

DEL*ETE 


== PURGE/LOG 

== SUBMIT/NOLOG_FILE/NOTIFY 
== MAIL/EDIT= (SEND, FORWARD, REPLY) 
== DIRECTORY /NOTRAILING /C0LUMN=2 
== DELETE /LOG /CONFIRM 


Define global symbols for commands used frequently 


DISPLAY 

REM 

MAIN 

HOST 

HR 

PROT 

TIME 


== MONITOR PROCESSES/TOPCPU 
== @DISK3: [MARCIA. PROG] REMINDER 
== SET DEFAULT DISK3 : [MARCIA] 

== SET HOST 4 

== SET HOST RED 5 

== SET PROT= (0:RWED, G:RWE,W:RWE) 6 

== @ [JONES] TIME 7 


Define logical names 

DEFINE TOOLS DISK3 : [MARCIA. TOOLS] 

DEFINE EQUIP DISK3 : [MARCIA. LISTS] EQUIPMENT . DAT 
DEFINE JON DAISY: : HARRIS 

Define keys to execute commands 

DEFINE/KEY PF3 "SHOW USERS" /TERMINATE 
DEFINE/KEY KP4 "SET HOST " 

Change the prompt string to a three-character 
abbreviation of the node name 

NODE = F$GETSYI ("NODENAME") 8 
PROMPT = F$EXTRACT (0,3, NODE) 

SET PROMPT = "" PROMPT' > " 

Type system notices 

TYPE SYS$SYSTEM:NOTICE . TXT 9 

Run a program that displays today's appointments 

RUN DISK3: [MARCIA. PROG] REMINDER 10 

ON ERROR THEN CONTINUE 11 


When you execute this command procedure, the following actions occur: 

i The F$MODE lexical function returns the mode (interactive, batch, network, 
or other) that the process is in when the LOGIN.COM procedure is executing. 
This statement causes the procedure to exit unless you are using the system 
interactively. You should test the mode at the beginning of your LOGIN.COM 
procedure to ensure that commands used only in interactive mode are not 
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executed in any other mode. I n some cases, these commands can abort 
non interactive processes. 

2 Defines the symbol Dl to represent the DIRECTORY command with the 
qualifiers /NOTRAI LI NG and /COLUM N=2. 

3 Defines the symbol DEL to represent the DCL command line DELETE /LOG 
/CONFIRM. Once this symbol is defined, you can delete a file by entering the 
symbol DEL followed by the file name. For example: 

$ DEL OLD_ACCOUNTS.TXT;! 

DELETE SYS$SYSDEVICE: [J0NES10LD_ACC0UNTS.TXT; 1 ? [N] : Y 
%DELETE-I-FILDEL, SYS$SYSDEVICE : [J0NES10LD_ACC0UNTS.TXT;! deleted 
(20 blocks) 

4 Defines the symbol H OST to be equivalent to the DCL command SET H OST. 
As with the SET HOST command, you must supply the name of the node to 
which you want to set host. 

5 Defines the symbol H R to be equivalent to the DCL command line SET HOST 
RED. In this case, the argument to the SET HOST command is supplied as 
part of the symbol definition. 

6 Defines the symbol PROT to be equivalent to the DCL command SET 
PROTECTION. As with the SET PROTECTION command, you must supply 
the name of the file that you want to make secure. 

7 Defines the symbol TIME to be equivalent to the DCL command that executes 
the command procedure 0 ON ES]TI ME.COM . 

8 This group of commands changes the DCL prompt to the first three characters 
of the node name. The F$GETSYI lexical function determines the node name. 
The F$EXTRACT lexical function extracts the first three characters of the 
name. The SET PROMPT command changes the prompt from a dollar sign to 
the first three characters of the node name followed by the right angle bracket 
character ( >) and a space. 

9 This command displays the system notices that your system manager keeps 
in the file SYS$SYSTEM:N OTICE.TXT. 

10 This command runs a user-written program that displays your daily 
appointments. If you have written programs that you always run after 

you log in, you might prefer to execute them directly from your LOGI N.COM 
file. 

11 This command requests the command interpreter to continue executing the 
procedure if any warning or error status value is returned when the command 
procedure is executed. 

The system manager assigns the file specification for your login command 
procedure. In most installations, the login command procedure is called 
LOGI N .COM . To execute a file other than the one named for your account, 
use the /COMMAND qualifier when you log in. See the description of the 
login procedure in the OpenVMS DCL Dictionary for information on using the 
/COMMAND qualifier. 

Your system manager can set up a captive account by placing the name of a 
special command procedure in the LGICMD field for your account. If you log into 
a captive account, you can perform only the functions specified in the command 
procedure for your account; you cannot use the complete set of DCL commands. 
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For more information on captive accounts, see the OpenVMS System Manager's 
Manual. 
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Lexical Functions: Obtaining and Manipulating 

Information 


Lexical functions are command language constructs that the DCL interpreter 
evaluates and substitutes before it interprets a command string. This chapter 
shows how to obtain and manipulate information within a command procedure by 
using lexical functions. It shows how to get information about the following: 

• Your process 

• The system 

• Files and devices 

• Logical names 

• Strings 

• Data types 

This chapter gives general information for some lexical functions. For complete 
descriptions of all lexical functions, see the OpenVMS DCL Dictionary or refer to 
DCL Help. 

Many lexical functions return information that you can also get from DCL 
commands. However, you can manipulate information in a command procedure 
more easily if you obtain it from a lexical function rather than from a command. 
For example, you can use either the F$ENVIRONMENT function or the SHOW 
DEFAULT command to obtain the name of your current default directory. The 
differences are as follows: 

• If you use the F$ENVIRONMENT function, you can assign the result to a 
symbol and then use this symbol later in the procedure. For example: 

$ DIR_NAME = F$ENVIRONMENT( "DEFAULT") 

$ SET DEFAULT DISK4:[TEST] 


$ SET DEFAULT ' DIR_NAME' 

The F$EN VI RON ME NT function returns the current default disk and 
directory and stores this value in the symbol Dl R_NAME. At the end of the 
procedure, you use the symbol Dl R_N AM E to restore the default with the 
SET DEFAULT command. 

• If you obtain the value of the current default directory with the SHOW 
DEFAULT command, rather than with the F$ENVI RONM ENT lexical 
function, you cannot assign this output to a symbol directly. Instead, the 
procedure is as follows: 
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$! Redirect the output of the SHOW DEFAULT command to a file. 
$ DEFINE/SUPERVISOR_MODE SYS$OUTPUT DISK4 : [TEST] TEMPFILE . DAT 
S SHOW DEFAULT 
$ DEASSIGN SYS$OUTPUT 
$ ! 

$ OPEN/READ DIR_FILE DISK4 : [TEST] TEMPFILE . DAT 
S READ DIR_FILE DIR_NAME, 

$ SET DEFAULT ' DIR_NAME' 

$ CLOSE DIR_FILE 

S DELETE DISK4 : [TEST] TEMPFILE.DAT; * 


Open the file. 

Read the file. 

Reset the directory. 
Close the file. 
Delete the file. 


16.1 Obtaining Information About Your Process 

You can use the following lexical functions to obtain information about your 
process: 


F$DI RECTORY 
F$ENVIRONMENT 

F$GETJ Pi 

F$MODE 
F$PRIVILEGE 
F$PROCESS 
F $SETPRV 

F$U SE R 
F$VERIFY 


Returns the current default directory string. 

Returns information about the command environment for your 
process. 

Returns accounting, status, and identification information 
about your process or about other processes on the system. 

Shows the mode in which your process is executing. 

Indicates whether your process has the specified privileges. 

Returns the name of your process. 

Sets the specified privileges. This function also indicates 
whether the specified privileges were previously enabled before 
you used the F$SETPRV function. 

Returns your user identification code (UIC). 

Indicates whether verification is on or off. 


You often change process characteristics for the duration of a command procedure 
and then restore them. Table 16-1 shows process characteristics that are 
commonly changed in command procedures; it also gives the lexical functions 
that save these characteristics and the DCL commands that restore the original 
settings. 

Note that, if you save process characteristics, you need to ensure that an error 
or Ctrl/Y interruption does not cause the procedure to exit before you restore the 
original characteristics. (See Chapter 15 for more information on handling errors 
and Ctrl/Y interruptions.) 


Table 16-1 Commonly Changed Process Characteristics 
Characteristic Operation Command or Lexical Function 


Control characters 

Save 

F$ENVIRONMENT("CONTROL") 


Restore 

SET CONTROL 

DCL prompt 

Save 

F$ENVIRONMENT("PROMPT") 


Restore 

SET PROMPT 

Default protection 

Save 

F$ENVI RON M E NT("P ROTE CTION ,r 


(continued on next page) 
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Table 16-1 (Cont.) Commonly Changed Process Characteristics 


Characteristic 

Operation 

Command or Lexical Function 


Restore 

SET PROTECTION/DEFAULT 

Key state 

Save 

Restore 

F $E N VI RON M E NT("KEY_STATE ") 

SET KEY 

Message format 

Save 

Restore 

F $E N VI RON M E NT("M E SSAGE") 

SET MESSAGE 

Privileges 

Save 

Restore 

F$PRIVI LEGE or F$SETPRV 

F $SETPRV or SET PROCESS/PRIVILEGES 

Verification 

Save 

Restore 

F$VERIFY or F$ENVIRONMENT 

F$VERIFY or SET VERIFY 


16.1.1 Changing Verification Settings 

You can use the F $VERI FY lexical function to disable verification for the duration 
of a command procedure. This prevents users from displaying a procedure's 
contents while executing the procedure. 

There are two types of verification: 

• Procedure verification 

Displays each command line as it is being executed 

• I mage verification 

Displays each data line as it is being processed 

By default, the SET [NO]VERIFY command and theF$VERIFY function turn 
both types of verification on or off. For example: 

$ ! Enable verification 

S ! 

$ TEMP = F$VERIFY (1) 

$ LOOP: 

$ INQUIRE FILE "File name" 

$ IF FILE . EQS . " " THEN EXIT 

$ PRINT 'FILE' 

$ GOTO LOOP 

$ ! Disable verification 
$ ! 

$ TEMP = F$VERIFY (0) 

$ EXIT 

In general, the procedure and image verification settings in a procedure are the 
same (both on or both off). Flowever, if you decide to change the settings, save 
each verification setting separately. For example: 
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$ ! Save each verification state 
$ ! Turn both states off 

$ SAVE_VERIFY_IMAGE = F$ENVIRONMENT ( "VERIFY_IMAGE" ) 
$ SAVE_VERIFY_PROCEDURE = F$VERIFY(0) 


$ ! Restore original verification states 
$ SAVE_VERIFY_IMAGE = F$VERIFY (SAVE_VERIFY_PROCEDURE, - 
SAVE_VERIFY_IMAGE) 

The F$ENVIRONMENT function returns the current image verification 
setting and assigns this value to the symbol SAVE_VERI FY_I M AGE. Next, 
the F$VERIFY function returns the current procedure verification setting 
and assigns this value to the symbol SAVE_VERI FY_PROCEDURE. The 
F$VERIFY function disables both image and procedure verification. You can 
use the F$ENVI RONMENT function to obtain the procedure verification setting 
before you disable verification with F$VERIFY. Flowever, it is shorter to use 
F$VERIFY to accomplish both tasks in one command line, as shown in the 
previous example. 

At the end of the procedure, the F$VERI FY function restores the original settings 
(specified by the symbols SAVE_VERI FY_PROCE DU RE and SAVE_VERIFY_ 
IMAGE.) 


Note 

If you are using time-stamping, remember that it applies only if 
verification is enabled. For more information on time-stamping and 
the SET PREFIX command, see the OpenVMS DCL Dictionary or refer to 
DCL help. 


16.1.2 Changing Default File Protection 

You may want to change the default file protection within a command procedure. 
The following command procedure changes the default protection associated with 
files created while the procedure is executing. The procedure restores the original 
default file protection before terminating. 

$ SAVE_PR0T = F$ENVIRONMENT( "PROTECTION") 

$ SET PROTECTION = ( SYSTEM :RWED, OWNER :RWED, GROUP, WORLD) /DEFAULT 


$ SET PR0TECTI0N=('SAVE_PR0T') /DEFAULT 
$ EXIT 

Note that the F$ENVIRONMENT function returns the default protection code 
using the syntax required by the SET PROTECTION command. This lets you use 
the symbol SAVE_PROT with the SET PROTECTION command to restore the 
original default file protection. 
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16.2 Obtaining Information About the System 

You can use the following lexical functions to obtain information about the 
system: 


F$CONTEXT 

F$CSID 

F$GETQUI 

F$GETSYI 

F$IDEIMTIFIER 

F$MESSAGE 
F$PI D 

F$TIME 


Specifies selection criteria to use with the F $P I D function. The 
F$CONTEXT function enables the F$PID function to obtain 
information about processes from any node in a VMScluster. 

Returns a VMScluster identification number and updates the 
context symbol to point to the current position in the system's 
VMScluster node list. 

Returns information about queues, batch and print jobs 
currently in those queues, form definitions, and characteristic 
definitions kept in the system job queue file. 

Returns information about your local system or about a node in 
your VMScluster (if your system is part of a VMScluster). 

Converts identifiers from named to numeric format or from 
numeric to named format. 

Returns the message text associated with a status code. 

Returns the process identification (PID) number for processes 
that you are allowed to examine. 

Returns the current date and time. 


The following sections describe how to obtain information about the system. 
For more information on each of these lexical functions, see the OpenVMS DCL 
Dictionary or refer to online help. 


16.2.1 Determining Your VMScluster Node Name 

If your system is part of a VMScluster environment where you can log in to 
many different nodes, you can set the DCL prompt to indicate which node you 
are currently using. To do this, include the F$GETSYI function in your login 
command procedure to determine the node name. Then use the SET PROMPT 
command to set a unique prompt for the node. For example: 

$ NODE = F$GETSYI ("NODENAME") 

$ SET PROMPT = " ' ' NODE' $ " 


If you want to use only a portion of the node name in your prompt string, use the 
F$EXTRACT function to extract the appropriate characters. See Section 16.5.2 
for more information on extracting characters. 

16.2.2 Obtaining Information About Queues 

You can use the F$GETQUI function to get many types of information about 
batch and print queues. You must have either read access to the job or SYSPRV 
or OPER privilege to obtain information about jobs and files in queues. 

The following example shows how to determine if the batch queue VAX1_BATCH 
is in a stopped state. The value returned is either true or false. If the queue is 
not stopped, the command procedure submits a job to the queue. 
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$ QSTOPPED = F$GETQUI ( "DISPLAY_QUEUE" , "QUEUE_STOPPED" , "VAX1_BATCH" ) 
$ IF QSTOPPED THEN GOTO NOBATCH 
$ SUBMIT/QUEUE=VAX1_BATCH TEST.COM 
$ NOBATCH: 


16.2.3 Obtaining Information About Processes 

You can use the F $PI D function to get the process identification (PI D) number for 
all processes that you are allowed to examine. You can obtain PI D numbers for 
all processes on the system if you have WORLD privilege. You can obtain PID 
numbers for all processes in your group if you have GROUP privilege. If you have 
neither GROUP nor WORLD privilege, you can obtain only the PID number for 
your process. 

The following example shows how to obtain and display the PI D numbers for the 
processes you are allowed to examine: 

$ ! Display the time when this procedure 
$ ! begins executing 
$ WRITE SYS$0UTPUT F$TIME () 

$ ! 

$ CONTEXT = "" 

$ START: 

$ ! Obtain and display PID numbers until 
$ ! F$PID returns a null string 
$ ! 

$ PID = F$PID (CONTEXT) 

$ IF PID . EQS. "" THEN EXIT 
$ WRITE SYS$0UTPUT "Pid — "PID'" 

$ GOTO START 

In the previous example, the system uses the symbol CONTEXT to hold a pointer 
into the system list of PID numbers. Each time through the loop, the system 
changes the pointer to locate the next PID number in the list. The procedure 
exits after all PID numbers have been displayed. 

After you obtain a PID number, you can use the F$GETJ PI function to obtain 
specific information about the process. For example, the following procedure 
displays the PI D number and the UIC for each process: 

$ CONTEXT = "" 

$ START: 

$ ! Obtain and display PID numbers and UICs 
$ ! 

$ PID = F$PID (CONTEXT) 

$ IF PID .EQS. "" THEN EXIT 
$ UIC = F$GETJPI (PID, "UIC") 

$ WRITE SYS$0UTPUT "Pid — "PID' Uic— "UIC' " 

$ GOTO START 

Note that you can shorten this command procedure by including the F$GETJ PI 
function within the WRITE command, as follows: 

$ CONTEXT = "" 

$ START: 

$ PID = F$PID (CONTEXT) 

$ IF PID .EQS. "" THEN EXIT 

$ WRITE SYS$0UTPUT "Pid — "PID' Uic — "F$GETJPI (PID, "UIC") ' " 

$ GOTO START 
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To obtain information about processes from any node in a VMScluster, use the 
F$CONTEXT function. I n the following example, F$CONTEXT is called three 
times to set up selection criteria. The first call requests that the search take 
place on all nodes in the VMScluster. The second call requests that only the 
processes whose user name either starts with an M or is SYSTEM be processed. 
The third call restricts the selection to those processes whose current privileges 
include both SYSPRV (system privilege) and OPER (operator) and can have other 
privileges set. 

The command lines between the labels "loop" and "endloop" continually call 
F $P I D to obtain the processes that meet the criteria set up in the F $CONTEXT 
calls. After retrieving each PID number, F$GETJ PI is called to return the name 
of the image running in the process. Finally, the procedure displays the name of 
the i mage. 

I n case of error or a Ctrl/Y operation, control is passed to error and the context 
is closed if necessary. In this example, note the check for the symbol type 
PROCESS_CONTEXT. If the symbol has this type, selection criteria must be 
canceled by a call to F$CONTEXT. If the symbol is not of the type PROCESS_ 
CONTEXT, either selection criteria have not been set up yet in F$CONTEXT, or 
the symbol was used with F$PID until an error occurred or until the end of the 
process list was reached. 


$! Establish an error and Ctrl/Y handler 

S! 

$ ON ERROR THEN GOTO error 
$ ON C0NTR0L_Y THEN GOTO error 

S! 


$ ctx = "" 

$ temp = F$C0NTEXT ("PROCESS", ctx, 
$ temp = F$C0NTEXT ("PROCESS", ctx, 
$ temp = F$C0NTEXT ("PROCESS", ctx, 

S! 

$!Loop over all processes that meet 
$ I Print the PID number and the name 
S! 


"NODENAME", , "EQL" ) 
"USERNAME", "M*, SYSTEM" , "EQL" ) 
"CURPRIV" , "SYSPRV, OPER", "ALL") 

the selection criteria, 
of the image for each process. 


$loop: 

S pid = F$PID (ctx) 

$ IF pid . EQS . "" 

$ THEN 

S GOTO endloop 

$ ELSE 

$ image = F$GETJPI (pid, "IMAGNAME") 

$ SHOW SYMBOL pid 

$ WRITE SYS$OUTPUT image 

$ GOTO loop 

$ ENDIF 

$!The loop over the processes has ended. 

$ ! 

$endloop: 

$ ! 

$ EXIT 
$ ! 

$!Error handler. Clean up the context's memory with 
$!the CANCEL selection item keyword. 

$ ! 

$error : 

$ IF F$TYPE (ctx) . eqs . "PROCESSJCONTEXT" THEN - 
-$ temp = F$C0NTEXT ("PROCESS", ctx, "CANCEL") 

$! 

$ EXIT 
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16.3 Obtaining Information About Files and Devices 

You can use the following lexical functions to obtain information about files and 
devices: 

F$DEVICE Returns the device names of all devices on a system that 

meet the specified selection criteria 

F$FILE_ATTRIBUTES Returns information about file attributes 

F$GETDVI Returns information about a specified device 

F $PARSE Parses a file specification and returns the requested field 

or fields 

F$SEARCFI Searches a directory for a file 

The following sections describe how to obtain some commonly used file 
information. 

16.3.1 Searching for Devices 

To get information on a particular device by using the system service $GETDVI, 
you must provide the device name to the service. If you do not know the device 
name, you can find it by using the lexical function F$DEVICE. 

The F$DEVICE function allows wildcard searches based on the device name, the 
device class, or the device type. To do a search based on device type, you must 
also specify a device class. 

You can use the F$DEVICE function in a loop in a command procedure to 
return device names that match the specified selection criteria. Each time the 
F$DEVICE function is executed, it returns the next device on the system that 
matches the selection criteria. Note that devices are returned in no particular 
order. After the last device name is returned, the next F$DEVICE function call 
returns a null string. 

The command procedure in the following example displays the device names of 
all the RA60s on a unit numbered 0: 

$ START: 

$ DEVICE_NAME = F$DEVICE ("*0 : "DISK", "RA60") 

$ IF DEVICE_NAME . EQS . "" THEN EXIT 
$ SHOW SYMBOL DEVICE_NAME 

$ GOTO START 

16.3.2 Searching for a File in a Directory 

Before processing a file, a command procedure should use the F$SEARCFI 
function to test whether the file exists. For example, the following command 
procedure uses F$PARSE to apply a device and directory string to the file 
STATS.DAT. Then the procedure uses the F$SEARCFI function to determine 
whether STATS.DAT is present in DISK3:[| ONES.WORK], If it is, the command 
procedure processes the file. Otherwise, the command procedure prompts for 
another input file. 

$ FILE = F$PARSE ("STATS. DAT", "DISK3: [JONES. WORK]",,, "SYNTAX_0NLY") 

$ IF F$SEARCH (FILE) .EQS. "" THEN GOTO GET_FILE 
$ PR0CESS_FILE : 


$ GET_FILE : 

$ INQUIRE FILE "File name" 
$ GOTO PR0CESS_FILE 
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After determining that a file exists, the procedure can use the F$PARSE or the 
F $F I LE_ATTRI BUTES function to get additional information about the file. For 
example: 

S IF F$SEARCH("STATS.DAT") . EQS. "" THEN GOTO GET_FILE 
$ PROCESS_FILE : 

$ NAME = F$PARSE ( "STATS .DAT" , , "NAME") 


$ GET_FILE : 

$ INQUIRE FILE "File name" 

$ GOTO PROCESS_FILE 

16.3.3 Deleting Old Versions of Files 

If a command procedure creates files that you do not need after the procedure 
terminates, delete or purge these files before you exit from the procedure. Use 
the PURGE command to delete all versions except the most recent one. Use the 
DELETE command with a version number to delete a specific version of the file 
or with a wildcard character in the version field to delete all versions of the file. 

To avoid error messages when using the DELETE command within a command 
procedure, use the F$SEARCH function to verify that a file exists before you try 
to delete it. For example, you can write a command procedure that creates a file 
namedTEMP.DAT only if certain modules are executed. The following line issues 
the DELETE command onlyifTEMP.DAT exists: 

$ IF F$SEARCH( "TEMP. DAT") .NES. "" THEN DELETE TEMP . DAT ; * 

16.4 Translating Logical Names 

You can use the following lexical functions to translate logical names: 

F$LOGICAL Returns the equivalence string for a logical name. 

F$TRNLNM Returns either the equivalence string or the requested attributes for a 
logical name. 


Note 

TheF$TRNLNM function supersedes the F$LOGI CAL function that was 
used in earlier versions of the OpenVMS operating system. You should 
use F$TRNLNM (instead of F$LOGICAL) to ensure that your command 
procedure processes logical names using the current system techniques. 


I n some situations, you may want to use logical names rather than symbols as 
variables in command procedures. Programs can access logical names more easily 
than they can access DCL symbols. Therefore, to pass information to a program 
that you run from a command procedure, obtain the information using a symbol. 
Then use the DEFINE command to equate the value of the symbol to a logical 
name. 

The following example tests whether the logical name NAMES has been defined. 
If it has, the procedure runs PAYROLL.EXE. Otherwise, the procedure obtains a 
value for the symbol FILE and uses this value to create the logical name NAMES. 
PAYROLL.EXE uses the logical name NAMES to refer to the file of employee 
names. For example: 
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$ ! Make sure that NAMES is defined 
$ IF F$TRNLNM( "NAMES") .NES. "" THEN GOTO ALL_SET 
$ INQUIRE FILE "File with employee names" 

$ DEFINE NAMES 'FILE' 

$ ! 

$ ! Run PAYROLL, using the file indicated by NAMES 
$ ALL_SET : 

$ RUN PAYROLL 


You can also use the F$TRNLNM function to assign the value of a logical name 
to a symbol. For example: 

$ DEFINE NAMES DISK4 : [JONES] EMPLOYEE_NAMES . DAT 
$ RUN PAYROLL 


$ FILE = F$TRNLNM (NAMES) 

$ WRITE SYS$OUTPUT "Finished processing ",FILE 

This command procedure defines a logical name that is used in the program 
PAYROLL. At the end of the procedure, the WRITE command displays a message 
indicating that the file was processed. Because the WRITE command does not 
translate logical names, you need to equate the logical name (NAMES) to a 
symbol (FILE). Then you can use the symbol FILE to display the file name. 


16.5 Manipulating Strings 

You can use the following lexical functions to manipulate character strings: 


F $CVTI M E 

F$EDIT 

F$ELEMENT 

F$EXTRACT 

F$FAO 

F$LENGTH 

F$LOCATE 


Returns information about a time string 
Edits a character string 

Extracts an element from a string in which the elements are separated 
by delimiters 

Extracts a section of a character string 
Formats an output string 
Determines the length of a string 

Locates a character or a substring within a string and returns the 
offset 


16.5.1 Determining If a String or Character Is Present 

One common reason for examining strings is to determine whether a character (or 
substring) is present within a character string. To do this, use the F$LENGTFI 
and the F$LOCATE functions. If the value returned by the F$LOCATE function 
equals the value returned by the F$LENGTH function, then the character you 
are looking for is not present. 

The following procedure requires a file name that includes the version number. 

To determine whether a version number is present, the procedure tests whether a 
semicolon (; ), which precedes a version number in a file name, is included in the 
file name that the user enters. 
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$ INQUIRE FILE "Enter file (include version number) " 
$ IF F$L0CATE FILE) .EQ. F$LENGTH (FILE) THEN - 
GOTO N0_VERSI0N 


The F$LOCATE function returns the offset for the semicolon. Offsets start with 
0; thus, if the semicolon were the first character in the string, the F$LOCATE 
function would return the integer 0. If the semicolon is not present within the 
string, the F$LOCATE function returns an offset that is one more than the 
offset of the last character in the string. This value is the same as the length 
returned by F$LENGTFI, which measures the length of the string starting with 
the number 1. 

16.5.2 Extracting Part of a String 

To extract a portion of a string, use either the F$EXTRACT function or the 
F$ELEMENT function. Use the F$EXTRACT function to extract a substring 
that starts at a defined offset. Use the F$ELEMENT function to extract part of a 
string between two delimiters. I n order to use either of these functions, you must 
know the general format of the string you are parsing. 

Note 

You do not need to use F$EXTRACT or F$ELEMENT to parse file 
specifications or time strings. Instead, useF$PARSE or F$CVTIME to 
extract the desired portions of file specifications or time strings. 


The following command procedure uses the F$EXTRACT function to extract the 
group portion of the UIC. This allows the procedure to execute a different set of 
commands depending on the user's UIC group. 

$ UIC = F$USER ( ) 

$ GR0UP_LEN = F$L0CATE (", ", UIC) - 1 
$ GROUP = F$EXTRACT (1, GR0UP_LEN, UIC) 

$ GOTO ' GROUP '.SECTION 


$ WRITERS_SECTION : 


$ MANAGERS_SECTION : 


First, the procedure determines the UIC with the F$USER function. Next, the 
procedure determines the length of the group name by using F $LOCATE to locate 
the offset of the comma. The comma separates the group from the user portion 
of a UIC. Everything between the left bracket and the comma is part of the 
group name. For example, the group name from the UIC [WRITERS,SMITFI] is 
WRITERS. 

After determining the length, the procedure extracts the name of the group 
with the F$EXTRACT function. The name starts with offset 1 and ends with 
the character before the comma. Finally, the procedure directs execution to the 
appropriate label. 
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Note that you can determine the length of the group name at the same time you 
extract it. For example: 

$ UIC = F$USER ( ) 

$ GROUP = F$EXTRACT (1, F$L0CATE ( " , " , UIC) - 1, UIC) 

$ GOTO ' GROUP '_SECTI0N 

If a string contains a delimiter that separates different parts of the string, use 
the F$ELEMENT function to extract the part that you want. For example, in a 
protection code, each type of access is separated by a comma: 

$ PROT = F$ENVIRONMENT( "PROTECTION") 

$ SHOW SYMBOL PROT 

PROT = "SYSTEM=RWED, OWNER=RWED, GR0UP=RE, WORLD" 

Thus, you can use F$ELEMENT to obtain different types of access by extracting 
the portions of the string between the commas. To determine system access, 
obtain the first element; to determine owner access, obtain the second element; 
and so on. 

The following example extracts the world access portion (the fourth element) from 
your default protection code. Note that when you use the F$ELEMENT function, 
element numbers start with zero. For this reason, use the integer 3 to specify the 
fourth element. For example: 

$ PROT = F$ENVIRONMENT( "PROTECTION") 

$ W0RLD_PR0T = F$ELEMENT (3, ", ",PR0T) 


In this example, the F$ELEMENT function returns everything between the third 
comma and the end of the string. Thus, if your default protection allowed read 
access for world users, the string " WORLD=R" would be returned. 

After you obtain the world access string, you may need to examine it further. For 
example: 

$ PROT = F$ENVIRONMENT( "PROTECTION") 

$ W0RLD_PR0T = F$ELEMENT (3, ", ",PR0T) 

$ IF F$ LOCATE W0RLD_PR0T) .EQ. F$LENGTH (W0RLD_PR0T) - 
THEN GOTO N0_W0RLD_ACCESS 


16.5.3 Formatting Output Strings 

You can use the WRITE command to write a string to a record. For example, the 
following command procedure uses the WRITE command to display the process 
name and PI D number for processes on the system: 

$ ! Initialize context symbol to get PID numbers 
$ CONTEXT = "" 

$ ! Write headings 

$ WRITE SYS$OUTPUT "Process Name PID" 

$ ! 

$ GET_PID: 

$ PID = F$PID (CONTEXT) 

$ IF PID . EQS. "" THEN EXIT 

$ WRITE SYS$OUTPUT F$GETJPI (PID, "PRCNAM") , " ", F$GETJPI (PID, "PID" ) 

$ GOTO GET_PID 
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Note that the output from the WRITE command inserts five spaces between the 
process name and the user name but the columns do not line up. For example: 

Process Name PID 
MARCHESAND 2CA0049C 
TRACTMEN 2CA0043A 

FALLON 2CA0043C 

ODONNELL 2CA00453 

PERRIN 2CA004DE 

CHAMPIONS 2CA004E3 

To line up the columns, you can use the F$FAO function to define record fields 
and place the process name and user name in these fields. When you use the 
F$FAO function, use a control string to define the fields in the record; then specify 
the values to be placed in these fields. For example, the following procedure uses 
the F$FAO function to define a 16-character field and a 12-character field. The 
F$FAO function places the process name in the first field, skips a space, and then 
places the PI D number in the second field. 

$ ! Initialize context symbol to get PID numbers 
$ CONTEXT = "" 

S ! Write headings 

$ WRITE SYS$OUTPUT "Process Name PID" 

$ ! 

$ GET_PID : 

$ PID = F$PID (CONTEXT) 

$ IF PID . EQS . "" THEN EXIT 

$ LINE = F$FA0 (" ! 16AS I12AS", F$GETJPI (PID, "PRCNAM") , F$GETJPI (PID, "PID" ) ) 

$ WRITE SYS$OUTPUT LINE 
$ GOTO GET_PID 

Now when you execute the procedure, the columns will be aligned: 

Process Name PID 

MARCHESAND 2CA0049C 

TRACTMEN 2CA0043A 

FALLON 2CA0043C 

ODONNELL 2CA00453 

PERRIN 2CA004DE 

CHAMPIONS 2CA004E3 

Another way to format fields in a record is to use a character string overlay. 

The following example uses an overlay to place the process name in the first 16 
characters (starting at offset 0) of the symbol RECORD. Then the PI D number is 
placed in the next 12 characters (starting at offset 17): 

$ ! Initialize context symbol to get PID numbers 
$ CONTEXT = "" 

$ ! Write headings 

$ WRITE SYS$0UTPUT "Process Name PID" 

S ! 

$ GET_PID : 

$ PID = F$PID (CONTEXT) 

$ IF PID .EQS. "" THEN EXIT 
$ RECORD [0, 16] := ' F$GETJPI (PID, "PRCNAM" ) ' 

$ RECORD [17, 12] := ' F$GETJPI (PID, "PID" ) ' 

S WRITE SYS$OUTPUT RECORD 
$ GOTO GET_PID 
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This procedure produces the same type of formatted columns you created with the 
F$FAO function: 


Process Name PID 

MARCHESAND 2CA0049C 

TRACTMEN 2CA0043A 

FALLON 2CA0043C 

ODONNELL 2CA00453 

PERRIN 2CA004DE 

CHAMPIONS 2CA004E3 


Note, however, that the F$FAO function is more powerful than a character string 
overlay. You can perform a wider range of output operations with the F$FAO 
function. 


16.6 Manipulating Data Types 

You can use the following lexical functions to convert data from strings to integers 
and from integers to strings: 


F$CVSI 

F $CVU I 

F$l NTEGE R 
F$STRING 
F $TY P E 


Extracts bit fields from a character string and converts the result, as a 
signed value, to an integer 

Extracts bit fields from a character string and converts the result, as 
an unsigned value, to an integer 

Converts a string expression to an integer 

Converts an integer expression to a string 

Determines the data type of a symbol 


16.6.1 Converting Data Types 

Use the F$INTEGER and F$STRING functions to convert between integers and 
strings. For example, the following command procedure converts data types. 

If you enter a string, the command procedure shows the integer equivalent. If 
you enter an integer, the command procedure shows the string equivalent. Note 
howtheF$TYPE function is used to form a label name in the GOTO statement; 
F$TYPE returns "STRING" or "INTEGER" depending on the data type of the 
symbol . 

$ IF PI . EQS. THEN INQUIRE PI "Value to be converted" 

$ GOTO CONVERT.' F$TYPE (PI) ' 

$ 

$ CONVERT.STRING: 

$ WRITE SYS$OUTPUT "The string "PI' is converted to "F$INTEGER(P1) ' " 

$ EXIT 
$ 

$ CONVERT.INTEGER: 

$ WRITE SYS$OUTPUT "The integer "PI' is converted to " F$STRING (PI) ' " 

$ EXIT 


16.6.2 Evaluating Expressions 

Some commands, such as INQUIRE and READ, accept only string data. If you 
use these commands to obtain data that you want to evaluate as an integer 
expression, use the F$l NTEGE R function to convert and evaluate this data. For 
example: 

$ INQUIRE EXP "Enter integer expression" 

$ RES = F$INTEGER('EXP' ) 

$ WRITE SYS$OUTPUT "Result is", RES 
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The following example shows sample output from this command procedure: 

Enter integer expression: 9+7 
Result is 16 

Note that you must place apostrophes ( ' ') around the symbol EXP when you use 
it as an argument for the F $1 NTEGER function. This causes DCL to substitute 
the value for EXP during the first phase of symbol substitution. I n the previous 
example, the value "9 +7" is substituted. When the F$l NTEGER function 
processes the argument "9 + 7," it evaluates the expression and returns the 
correct result. 

16.6.3 Determining Whether a Symbol Exists 

Use the F$TYPE function to determine whether a symbol exists. The F$TYPE 
function returns a null string if a symbol is undefined. For example: 


S IF F$TYPE (TEMP) . EQS . "" THEN TEMP = "YES" 
$ IF TEMP .EQS. "YES" THEN GOTO TEMP_SEC 


This procedure tests whether the symbol TEMP has been previously defined. If 
it has, then the current value of TEMP is retained. If TEMP is not defined, then 
the I F statement assigns the value "YES" to TEMP. 
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Processes and Batch Jobs: Using the 

OpenVMS Environment 


A process is an environment created by the OpenVMS operating system that lets 
you interact with the system. The system creates a process for you when you 
perform one of the following tasks: 

• Logging in 

The system creates a process for each interactive user. 

• Submitting a batch job 

The system creates a process for each batch job. When the batch job is 
completed, the system deletes the process. 

• Spawning a subprocess 

The system creates a process when you use the SPAWN command. 

• Running a program 

The system creates a process when you run a program using either the 
/DETACHED qualifier or the/UIC=uic qualifier. 

This chapter describes processes, how and when to use subprocesses, and how to 
use batch jobs. 


17.1 Interpreting Your Process Context 

Characteristics that a process uses, such as privileges, symbols, and logical 
names, form a process context. To display the process context for your current 
process, enter the SHOW PROCESS/ALL command. The following example 
shows a process context: 


ll-DEC-1994 13:30:37.12 1 User: CLEAVER 2 

Node: ZEUS 


Terminal : 

User Identifier: [DOC, CLEAVER] 5 
Base priority: 4 6 
Default file spec: DISKI : [CLEAVER] 7 


Process ID: 24E003DC 3 

Process name: CLEAVER_1 4 


Process Quotas: 8 

Account name: DOC 


CPU limit: 

Infinite 

Direct I/O limit: 

18 

Buffered I/O byte count quota: 

31808 

Buffered I/O limit: 

25 

Timer queue entry quota: 

10 

Open file quota: 

57 

Paging file quota: 

22276 

Subprocess quota: 

4 

Default page fault cluster: 

64 

AST quota: 

38 

Enqueue quota: 

600 

Shared file limit: 

0 

Max detached processes: 

0 

Max active jobs: 

0 
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Accounting information: 9 


Buffered I/O count: 


140 Peak working set size: 

383 

Direct I/O count: 


7 Peak virtual size: 

2336 

Page faults: 


304 Mounted volumes: 

0 

Images activated: 


1 


Elapsed CPU time: 

0 

00:00:00.55 


Connect time: 

0 

00:00:22.76 


Process privileges: 


10 


GROUP 

may 

affect other processes in same 

group 

TMPMBX 

may 

create temporary mailbox 


OPER 

operator privilege 


NETMBX 

may 

create network device 



Process rights identifiers: 11 

INTERACTIVE 
LOCAL 

SYS$NODE_ZEUS 


Process Dynamic Memory Area 
Current Size (bytes) 

12 

25600 

Current Total Size (pages) 

50 

Free Space (bytes) 

19592 

Space in Use (bytes) 

6008 

Size of Largest Block 

19520 

Size of Smallest Block 

24 

Number of Free Blocks 

3 

Free Blocks LEQU 32 Bytes 

1 

Processes in this tree: 

CLEAVER 

13 




CLEAVER_1 (*) 


i Current date and time 

The date and time when the SHOW PROCESS/ALL command is executed. 


2 User name 

The user name assigned to the account that is associated with the process. 

3 Process identification (PID) number 

A unique number assigned to the process by the system. The SHOW 
PROCESS command displays the PI D number as a hexadecimal number. 

4 Process name 

The name assigned to the process. Because process names are unique, 
the first process logged in under an account is assigned the user name. 
Subsequent processes logged in under the same account are assigned the 
terminal name. You can change your process name with the DCL command 
SET PROCESS/NAME. 

5 User identification code ( UIC ) 

The group and member numbers (or letters) assigned to the account that is 
associated with the process (for example, [DOC, CLEAVER]). Part of your UIC 
identifies the group to which you belong. Within a group, users are allowed to 
share files or system resources more freely than between groups. 

6 Priority 

The current priority of the process. 

7 Default file specification 

The current device and directory. Change your current defaults with the DCL 
command SET DEFAULT. 
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8 Process quotas 

The quotas (limits) associated with the process. Examine these quotas with 
the /QUOTAS or /ALL qualifiers of the SHOW PROCESS command. 

9 Accounting information 

The continuously updated account of the process's use of memory and CPU 
time. Examine this information with the /ACCOUNTI NG or /ALL qualifiers 
of the SHOW PROCESS command. 

10 Process privileges 

The privileges granted to your processes. Privileges restrict the performance 
of certain system activities to certain users. Examine your privileges with the 
/PRI VI LEGES or /ALL qualifiers of the SHOW PROCESS command. 

11 Process rights identifiers 

System-defined identifiers that are used in conjunction with access control list 
(ACL) protection. Identifiers provide the means of specifying the users in an 
ACL. An ACL is a security tool that defines the kinds of access to be granted 
or denied to users of an object, such as a file, device, or mailbox. 

12 Process dynamic memory area 

The process's current use of dynamic memory. Dynamic memory is allocated 
by the system to an image when that image is executing. When that memory 
is no longer needed by one process, the system allocates it to another process. 
Examine this information with the /MEMORY or /ALL qualifiers of the 
SHOW PROCESS command. 

13 Processes in this tree 

A list of subprocesses belonging to the parent process. An asterisk (*) 
appears after the current process. Examine this list with the SHOW 
PROCESS/SUBPROCESSES or /ALL command. 

17.2 Using Detached Processes 

A detached process is either interactive or noninteractive, depending on the 
parent process. Either you or the operating system perform the login, depending 
on the argument you provided to the DCL command RUN or the Create 
Process system service ($CREPRC). (Both RUN and $CREPRC execute the 
LOGINOUT.EXE image in SYS$SYSTEM.) 

17.3 Using Subprocesses 

The SPAWN command enables you to create a subprocess of your current process. 
Within this subprocess, you can interact with the system and log out of the 
subprocess to return to your parent process or switch between your parent 
process and subprocesses. Only one of your processes is executing at any time. 

Each user on the system is represented by a job tree. A job tree is a hierarchy 
of all your processes and subprocesses with your main process at the top. A 
subprocess is dependent on the parent process and is deleted when the parent 
process exits. By default, the subprocess assumes the name of the parent process 
followed by an underscore and a unique number. For example, if the parent 
process name is DOUGLASS, the subprocesses are named DOUGLASS_l, 
DOUGLASS_2, and so on. 
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Typically, you use a subprocess in one of the following ways: 

• To interrupt a task, perform a second task, then return to the original task 

You can use Ctrl A' to interrupt one task, spawn a subprocess to perform 
a second task, exit from the subprocess, and then enter the CONTI NUE 
command to return to the original task. By default, when you create a 
subprocess, the parent process hibernates and you are given control at DCL 
level within the subprocess. Your default directory is the current directory 
of the parent process. For example, if you press Ctrl/Y to interrupt an EVE 
editing session, enter the CONTI NUE command and press Ctrl/W to refresh 
the screen. 

• To perform a second task while continuing to work on your original task 

You can create the subprocess with the SPAWN/NOWAIT command. SPAWN 
/NOWAIT generates a noninteractive, batch-like subprocess and is used to 
execute only commands that do not require input. 

Because both the parent and the subprocess are executing concurrently, 
both attempt to control the terminal. To prevent conflicts, also specify the 
following: 

- /OUTPUT qualifier 

I ndicates that the subprocess should write output to a specified file rather 
than to the terminal 

SPAWN command parameter or /INPUT qualifier 

I ndicates that the subprocess should execute the specified commands 
rather than reading input from the terminal 

When you specify the /INPUT qualifier of the SPAWN command, the 
subprocess is created as a noninteractive process that exits upon encountering 
a severe error or an end-of-file indicator. At DCL level, Ctrl/Z is treated as an 
end-of-file indicator. 

17.3.1 Creating a Subprocess 

In the following example, a user interrupts a command image (the TYPE 
command) by pressing Ctrl/Y, spawns a subprocess, exits from the subprocess, 
and returns to the original process: 


17-4 


Processes and Batch Jobs: Using the OpenVMS Environment 

17.3 Using Subprocesses 


$ TYPE MICE . TXT 

Once the weather turns cold, mice may find a crack in the 
foundation and enter your house. They are looking for food and 
shelter from the harsh weather ahead. 


| Ctrl/Y | 

$ SPAWN 

%DCL-S-SPAWNED, process D0UGLASS_1 spawned 
%DCL-S-ATTACHED, terminal now attached to process D00GLASS_1 
S MAIL 
MAIL> 


MAIL> EXIT 
$ LOGOUT 

Process D0UGLASS_1 logged out at 31-DEC-1994 12:42:12.46 
%DCL-S-RETURNED, control returned to process DOUGLASS 
$ CONTINUE 

Once inside, they may gnaw through electrical wires and raid 
your food. Because mice reproduce so quickly, what started 
as one or two mice can quickly become an invasion. If you seal 
the cracks and holes on the exterior of your foundation, you can 
prevent these rodents from ever getting in. 

Because each process you create is unique, commands executed in one process do 
not usually affect any other process. However, because control of the terminal 
passes between processes, commands that affect the terminal characteristics 
(for example, SET TERMINAL) affect any process controlling that terminal. For 
example, if one process inhibits echoing and exits without restoring it, echoing 
remains inhibited for the next process that gains control of the terminal. Reset 
any altered terminal characteristics with the SET TERM I NAL command. 

17.3.2 Exiting from a Subprocess 

To exit from a subprocess created by the SPAWN command, use one of the 
following commands: 

• LOGOUT 

When you exit from a subprocess with the LOGOUT command, the subprocess 
is deleted (along with any subprocesses that it created) and you are returned 
to the parent process. 

• ATTACH 

When you exit from a subprocess with the ATTACH command, the subprocess 
hibernates and control of your terminal is transferred to the specified 
process. You must specify either a process name as a parameter to the 
ATTACH command or a process identification (PID) number as a value of 
the /I DENTI FI ER qualifier of the ATTACH command. The following example 
shows how to exit from the subprocess DOUGLASS_l and attach to the 
process DOUGLASS: 
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$ ATTACH DOUGLASS 

%DCL-S-RETURNED, control returned to process DOUGLASS 
S SHOW PROCESS 

ll-DEC-1994 10:34:58.50 VTA303 User: DOUGLASS 

Pid: 25C002B4 PROG, name: DOUGLASS UIC: [200,200] 

Priority: 4 Default file spec: SYS$SYSDEVICE: [DOUGLASS] 

Devices allocated: $11$VTA303: 

17.3.3 Subprocess Context 

The subprocess context is the environment that the subprocess inherits from the 
parent process. By default, a subprocess inherits the following items: defaults, 
privileges, symbols, logical names, control characters, message format, verification 
state, and key definitions. Collectively, these items create an environment for 
the subprocess. The following items, however, are not inherited from the parent 
process: 

• Process identification (PID) number 

The system assigns each created subprocess a unique PI D number. 

• Process name 

By default, the subprocess name consists of the name of the parent process 
followed by an underscore and an integer. Use the /PROCESS qualifier of the 
SPAWN command to specify a process name other than the default. A process 
name must be unique. 

• Created commands 

Commands that are defined by a parent process using the SET COMMAND 
command are not copied to a subprocess. To use a created command in a 
subprocess, you must use SET COMMAND to create that command for the 
subprocess. 

• Authorize privileges 

When you spawn to a subprocess, the process context contains the privileges 
of the parent process, not the privileges that you are authorized to enable. 

For example, if you spawn to a subprocess while in Mail and want to perform 
a privileged operation, you must set the proper privilege in the parent process 
before you invoked Mail. 

You can use the following SPAWN command qualifiers to prevent the subprocess 
from inheriting a number of these items: 


SPAWN Command Qualifier 

Items Inhibited or Changed 

/CARRI AGE_CONTROL, /PROMPT 

DCL prompt 

/NOCLI 

CLI (command language interpreter; 

DCL by default) 

/NOKEYPAD 

Keypad definitions 

/N O LOG ICAL_N AMES 

Logical names 

/NOSYMBOL 

Symbols 


The /SYMBOL and /LOGICAL_NAMES qualifiers do not affect system-defined 
symbols (such as $SEVERITY and $STATUS) or system-defined logical names 
(such as SYS$COMMAND and SYS$OUTPUT). Symbols are described in 
Chapter 14, and logical names are described in Chapter 13. 
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Because copying logical names and symbols to a subprocess can be time- 
consuming (a few seconds), you may want to use the /NOLOGI CAL NAMES 
and /NOSYMBOL qualifiers to the SPAWN command unless you plan to use the 
logical names or symbols in the subprocess. If you use subprocesses frequently, 
the ATTACH command provides the most efficient way to enter and exit a 
subprocess. This method allows you to transfer control quickly between the 
parent process and subprocess rather than repeatedly waiting for the system to 
create a new subprocess for you. 

17.4 Connecting to a Disconnected Process on Virtual Terminals 

If virtual terminals are enabled and a modem line connection is lost, a process 
remains active on the system as a disconnected virtual terminal process. You 
must reconnect to the process within the time period specified by the system 
manager (the default value is 900 seconds or 15 minutes). If you fail to reconnect 
to the process before this time expires, the system deletes the process. 

Note 

You can connect only to a virtual terminal process associated with your 
user identification code (UIC). 


A terminal can be disconnected in the following circumstances: 

• You lose the modem signal between the host and the terminal. 

• You press the BREAK key on a terminal with the TT2$M_SECURE 
characteristic set. 

• You enter the DCL command DISCONNECT. 

• You enter the DCL command CONNECT/CONTI NUE. 

If your process is disconnected, you have the option of reconnecting to the old 
process and returning to the state it was in before you were disconnected. When 
you log in, the system prompts you as follows: 

You have the following disconnected process: 

Terminal Process name Image name 

VTA52 : RW00DS (none) 

Connect to above listed process [YES] : 

If you press the Return key or enter Yes, you are logged out of your current 
process as if automatic execution of the DCL command CONNECT/CONTINUE 
had been performed for you. If you enter No or if you delay too long in responding 
(so that a response period timeout occurs), you remain logged in to your new 
process. You lose the ability to connect to the old process. 

When you have multiple disconnected sessions, you are prompted for the name 
of the virtual terminal to which you want to reconnect. If you do not want to 
connect to any of the displayed sessions, enter No. 
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17.4.1 Removing Disconnected Processes 

The system automatically removes your disconnected processes after a certain 
interval. You can conserve system resources, however, if you directly log out of 
any disconnected processes, as follows: 

1. Enter the DCL command SHOW USERS to determine if you have other 
disconnected jobs. 

2. Enter the DCL command CONNECT/LOGOUT to log out of the current 
process. Connect back through each of the associated virtual terminals (as 
noted by the terminal prefix VTA) until you reach the last existing process. 

3. Enter the DCL command LOGOUT. 

17.4.2 Managing Disconnected Processes 

Virtual terminals allow you to maintain more than one disconnected process at a 
time. You must keep in mind, however, that while you are logged in to a virtual 
terminal, the physical terminal is disconnected. Any I/O requests directed to 
a device other than the physical terminal associated with your current virtual 
terminal process will enter a waiting state. The pending process will terminate 
when the timeout period expires. If, however, you reconnect to the physical 
terminal that is to receive the I/O request, the process continues from the point 
at which it entered the waiting state. Naming each process with a name that 
relates to its context makes it easier to reconnect to the desired process. 

For example, a user named SMITH running a process to edit a file might use the 
SET PROCESS/NAME command to name the process SMITH_EDIT. In this way, 
SMITH could easily determine which process to connect to in order to continue 
editing. 

A system manager can restrict the use of virtual terminals systemwide or on a 
per terminal basis. 

17.5 Working with Batch Jobs 

A batch job is a noninteractive process. Because a batch job executes in a process 
of its own, you can have two or more processes doing different things at the 
same time. For example, you can perform a task interactively while the system 
executes a program or command procedure in batch mode. You can use batch jobs 
to run command procedures that take a long time to execute, to execute command 
procedures or programs after hours, or to run certain programs at a reduced 
priority (for example, if the program uses a disproportionate amount of system 
resources). 

When you submit a batch job, the system creates a detached process with your 
account and process characteristics. The system runs the job from that process 
and deletes the process when the job completes. The system also executes the 
system login command procedure (SYLOGIN.COM) and your login command 
procedure (LOGIN.COM) and then executes the command procedures in the 
batch job. As these procedures execute, output is written to a log file. When the 
batch job completes, you can print the log file or save it in one of your directories. 

The rest of this chapter describes how to do the following: 

• Submit batch jobs 

• Pass data to batch jobs 

• Control batch job output 
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• Change batch job characteristics 

• Control jobs in a batch queue 

• Synchronize batch jobs 

17.5.1 Submitting Batch Jobs 

To run a job in batch mode, submit your job to a batch queue (a list of batch jobs 
waiting to execute) by entering the DCL command SUBMIT. When you submit 
a job, it is directed to the default batch queue SYS$BATCH where it is added 
to the end of the queue of jobs waiting to be executed. When the jobs preceding 
yours are completed, your job is executed. On an OpenVMS system, the number 
of batch jobs that can execute simultaneously is specified when the batch queue 
is created by the system manager. 

By default, the SUBMIT command uses a file type .COM. For example, the 
following command enters J OBl.COM into SYS$BATCH : 

$ SUBMIT J0B1 

Job J0B1 (queue SYS$BATCH, entry 651, started on SYS$BATCH) 

The system displays the name of the job, the queue containing the job, and the 
entry number assigned to the job. You receive the DCL prompt after your job 
is submitted to the batch queue. If you need to reference your batch job in any 
DCL commands (DELETE/ENTRY, for example), do so by using the job entry 
number. (You can obtain the job entry number by using the SHOW ENTRY 
command.) Note that if multiple procedures are submitted in a batch job, the 
batch job terminates when any procedure exits with an error or fatal (severe) 
system message. 

Your batch job does not necessarily have to start running at the time you submit 
it to the batch queue. To specify a different time, enter the SUBMIT/AFTER 
command. I n the following example, the job is submitted after 11:30 p.m.: 

$ SUBMIT/AFTER=23 : 30 J0B1.C0M 

When you submit a command procedure for batch execution, the system saves 
the complete file specification for the command procedure, including the version 
number. If you update a command procedure after you submit it, the batch job 
executes the version of the command procedure that you submitted rather than 
the new version. 

Because your login defaults are not usually the defaults needed to access files 
mentioned in your command procedures, use one of the following methods to 
ensure that the correct files are accessed: 

• Use complete file specifications— When referring to a file in a command 
procedure or when passing a file to a command procedure, include the device 
and directory names as part of the file specification. 

• Use the SET DEFAULT command— Before referring to a file in a command 
procedure, use the SET DEFAULT command at the beginning of the command 
procedure to specify the proper device and directory. 

As a batch job executes, it writes output to a log file. By default, the log file has 
the same name as the command procedure you submit with the file type .LOG. 
When the job is finished, the system prints the log file and deletes it from your 
directory. See Section 17.5.3 for information on saving log files. 
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Checking for Batch Jobs in Your Login Command Procedure 

Each time you submit a batch job, the system executes your login command 
procedure. You can cause sections of your login command procedure to be 
included or omitted when you execute batch jobs by using the F$MODE( ) lexical 
function to test for batch jobs. 

For example, you might have a section in your login command procedure that 
includes commands, logical names, and symbols that you use exclusively for 
batch jobs. You might label this section BATCFI_COMMANDS, then include the 
following command at the beginning of your login command procedure: 

IF F$M0DE () . EQS. "BATCH" THEN GOTO BATCHJCOMMANDS 


To prevent the system from executing any commands in your login command 
procedure when you submit a batch job, place the following command at the 
beginning of the procedure: 

IF F$M0DE() .NES. "INTERACTIVE" THEN EXIT 

You can place this command anywhere in your login command procedure. When 
you submit a batch job, the system executes your login command procedure only 
to the point at which the preceding command is placed. 

Submitting Multiple Command Procedures 

When you enter the SUBMIT command, you can specify several command 
procedures to be executed in one job. For example: 

$ SUBMIT UPDATE, SORT 

Job UPDATE (queue SYS$BATCH, entry 207) started on SYS$BATCH 

This SUBMIT command creates a batch job that executes UPDATE.COM then 
SORT.COM . Unless you specify a name with the /NAM E qualifier, the SUBMIT 
command uses the name of the first command procedure as the job name. Note 
that if an error causes any command procedure in a job to exit, the entire job 
terminates. 

When a batch job executes, the operating context of the first procedure 
(UPDATE.COM) is not preserved for the second procedure (SORT.COM). The 
system deletes local symbols created by UPDATE.COM before SORT.COM 
executes. Global symbols, however, are preserved. 

You cannot specify different parameters for individual command procedures 
within a single job. The following example passes the same two parameters to 
UPDATE.COM andtoSORT.COM: 

$ SUBMIT UPDATE, SORT/PARAMETERS = - 

_$ (DISKI: [ACCOUNT.BILLSJDATA.DAT, DISK2 : [ACCOUNT] NAME . DAT) 

$ Job UPDATE (queue SYS$BATCH, ENTRY 208) started on SYS$BATCH 

17.5.2 Passing Data to Batch Jobs 

The default input stream (SYS$I NPUT) for a batch job is the command procedure 
that is being executed. Because a detached process is executing the batch job, 
you cannot redefine SYS$INPUT to the terminal (as you can with command 
procedures that you execute interactively.) To pass input to a batch job, use one 
of the following techniques: 

• I nclude the data in the command procedure itself. 
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• Temporarily define SYS$I N PUT as a file. 

• Pass parameters to the command procedure when you submit it for execution. 

To include data in a command procedure, place the data on the lines after the 
command or image. For example: 

S! Execute AVERAGE . EXE 

$ RUN AVERAGE 

647 

899 

532 

401 

$ EXIT 

To define SYS$I NPUT temporarily as a file, use the DEFI N E/USE R_M ODE 
command as in this example: 

S DEFINE/USERJ40DE SYS$INPUT STATS .DAT 
$ RUN AVERAGE 
S EXIT 

To pass parameters to a command procedure, use the /PARAMETERS qualifier 
when you submit the batch job as in this example: 

$ SUBMIT/PARAMETERS= (DISKI : [PAYROLL] EMPLOYEES . DAT) CHECKS 
Job CHECKS (queue SYS$BATCH, entry 209) started on SYS$BATCH 

Note that you cannot specify different parameters for individual command 
procedures within a single job. Use separate SUBMIT commands if you need to 
pass different groups of parameters. 


Note 

The SHOW QUEUE/FULL command displays full information about jobs 
in a batch queue. This display includes any parameters you pass to the 
procedure. Therefore, do not pass confidential information (such as a 
password) to a batch job. 


17.5.3 Controlling Batch Job Output 

By default, the log file has the same name as the first command procedure in the 
batch job and has the file type .LOG. The system writes output from a batch job 
to a log file once each minute. To specify a different time interval, include the 
SET OUTPUT_RATE command in your command procedure. 

If you attempt to use the EDT editor to read the log file while the system is 
writing to it, you receive a message indicating that the file is locked by another 
user. Wait a few seconds and try again. The EVE editor, however, allows you to 
read the batch job's log file. By specifying EDIT/TPU/READ_ONLY and the name 
of the log file, you can use EVE commands to move around the log file and ensure 
that any changes you make to the file are not saved. If you omit the /READ_ 
ONLY qualifier and modify the log file in any way, the batch job terminates. 

Because your batch job is a process that logs in under your user name and 
executes your login command procedure, the output from a batch job includes the 
contents of your login command procedure. The output also includes everything 
written to the batch job log file (command procedure output, error messages, and 
so on) and the full logout message. To prevent your login command procedure 
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from being written to the batch log file, add the following command to the 
beginning of your login command procedure: 

$ IF F$M0DE () . EQS. "BATCH" THEN SET NOVERIFY 

By default, the log file name is the name under which you submitted the job. 
Also by default, the log file has the file type .LOG and assumes the device 
and directory specified by your login defaults. To specify a different log file 
name when you submit the job, use the /LOG_NAME qualifier to the SUBMIT 
command. 

When the batch job completes, the log file is queued to the default system printer 
(SYS$PRI NT), printed, and deleted. To save the log file after printing it, use the 
/KEEP qualifier with the SUBM IT command. To save the log file without printing 
it, use the /NOPRI NT qualifier with the SUBMIT command. 

The batch job log file includes all output to SYS$OUTPUT and SYS$ERROR. It 
also includes, by default, all command lines executed in the command procedure. 
To prevent the command lines from being printed, use either the SET NOVERI FY 
command or the F$VERIFY lexical function in your command procedure. When 
the job completes, the system writes job termination information (using the long 
form of the system logout message) to the log file. 

If the SET VERI FY command is in effect, you can also learn the exact time when 
each command is executed by using the SET PREFIX command to time-stamp 
each command line. For information on time-stamping, see Section 15.4.2.5. 

When a batch job fails to complete successfully, you can examine the log file to 
determine the point at which the command procedure failed and the error status 
that caused the failure. 

Saving the Log File 

To save the log file, use either the /KEEP or the /NOPRI NTER qualifier. The 
/KEEP qualifier saves the log file after it is printed. The /NOPRI NTER qualifier 
saves the log without printing it. If you specify neither of these qualifiers, the 
default action occurs; the log file is queued to the default print queue SYS$PRINT 
and is deleted after it prints. The /KEEP and /NOPRI NTER qualifiers save the 
log file in your default login directory. The log file has the same name as the 
first command procedure in the batch job and the file type .LOG. To specify an 
alternate file name or directory name, or both, use the /LOG_FI LE qualifier. To 
rename and save the log file, you must use/LOG_FILE plus either /KEEP or 
/NOPRINTER. For example: 

$ SUBMIT/L0G_FILE=DISK2 : [JONES . RESULTS] /NOPRINTER - 
_$ DISK2: [JONES. RESULTS] UPDATE 

Reading the Log File 

You can use the TYPE command to read the log file to determine how much of the 
batch job has completed. However, if you attempt to display the log file while the 
system is writing to it, you receive a message indicating that the file is locked by 
another user. If this occurs, wait a few seconds and try again. 

Including All Command Output in the Batch Job Log 

Typically, a batch job command procedure that compiles, links, and executes a 
program creates additional printed output such as a compiler listing or a linker 
map. To produce printed copies of these files, a batch job command procedure 
can contain the PRINT commands necessary to print them, as in the following 
example: 
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$ FORTRAN/LIST BIGCOMP 
$ PRINT BIGCOMP. LIS 
$ LINK/MAP /FULL BIGCOMP 
$ PRINT BIGCOMP. MAP 

When this command procedure completes processing, there are three separate 
output listings: the batch job log, the compiler listing, and the linker map. 

If you want a batch job log to contain all output from the command procedure, 
including printed listings of compiler or linker output files, you can do either of 
the following: 

• Use the TYPE command instead of the PRI NT command in the command 
procedure. The TYPE command writes to SYS$OUTPUT. In a batch job, 
SYS$OUTPUT is equated to the batch job log file. 

• Use qualifiers on appropriate commands to direct the output to 
SYS$OUTPUT. 

The following example shows the second technique: 

$ FORTRAN/LI ST=SYS$OUTPUT BIGCOMP 
$ LINK/MAP=SYS$OUTPUT/FULL BIGCOMP 

When these commands are executed in a batch job, the output files from the 
compiler and the linker are written directly to the log file. Note that if you use 
this technique, the output files are not saved on disk unless you save the log file. 

17.5.4 Changing Batch Job Characteristics 

After a job has been submitted to the queue but before the job starts to execute, 
you can use the SET ENTRY or the SET QUEUE/ENTRY command with the 
appropriate qualifiers to change characteristics associated with the job. For 
example, to change the name of a batch job while it is pending in a batch queue, 
you can enter either of the following commands: 

$ SET QUEUE / ENTRY=2 0 9 /NAME=NEW_NAME SYS$BATCH 
$ SET ENTRY 209 /NAME=NEW_NAME 

Both of these commands change the name of job number 209 to NEW_NAME. 

The following list contains some of the changes you can make with the SET 
ENTRY or SET QUEUE/ENTRY commands. For a complete list of qualifiers, 
see the OpenVMS DCL Dictionary. Note that most of the qualifiers allowed 
with the SUBMIT command can also be used with SET ENTRY and the SET 
QUEUE/ENTRY commands. 

You can make the following changes: 

• Delay processing of a job. 

Use the /AFTER qualifier to specify a time after which the job can be 
executed. Use the /FI OLD qualifier to hold a job until you explicitly release it. 

• Release a job. 

Use the /NOHOLD or /RELEASE qualifier to release a job that was submitted 
with the /HOLD or /AFTER qualifiers. 

• Send a job to a different queue. 

Use the /REQUEUE qualifier to change the queue on which the job will 
execute. 

• Change execution characteristics. 
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Change execution characteristics such as working set default, working set 
extent, working set size, job scheduling priority, and CPU time limit. 

• Change the parameters to be passed to a job. 

U se the /PARAM ETE RS qual ifier to change the parameters. 

17.5.5 Controlling Jobs in a Batch Queue 

Table 17-1 lists the SUBMIT command qualifiers you can use to control batch job 
characteristics. 


Table 17-1 Controlling Batch Job Characteristics 


SUBMIT Command 
Qualifier 

Description 

/AFTER 

Specifies a time after which the batch job can execute. The 
job remains in the batch queue until the specified time. To 
hold a job in the queue until you explicitly release it, use the 
/HOLD qualifier. (To release a job that is being held, use the 
SET ENTRY/RELEASE command.) 

/NAME 

Specifies a name for the batch job. Otherwise, the job name 
defaults to the file name of the first (or only) command 
procedure in the job. 

/NOTE 

Specifies a message string to appear as part of the display 
for a SHOW QUEUE/FULL command. Allows you to convey 
information about the job to the operator or system manager. 

/NOTIFY 

Requests notification of job completion. The system sends 
a message to your terminal when the batch job finishes 
executing. 

/PARAMETERS 

Passes parameters to a batch job. 

/NOPRINTER or /KEEP 

Saves a batch job log file. 

/QUEUE 

Sends a batch job to a queue other than SYS$BATCH. To 
execute a command procedure that is located on a remote node, 
usethe/REMOTE qualifier. This sends the job to SYS$BATCH 
at the remote node. 

/RESTART 

Enables you to restart the job if the system fails while the job 
is executing. 

/RETAIN 

Keeps a batch job in a queue after it completes. You can use 
the SHOW QUEUE or SHOW ENTRY commands to see the 
job's completion status. 


You can also specify execution characteristics such as working set default, 
working set extent, working set size, job scheduling priority, and CPU time limit. 

Displaying Jobs in a Batch Queue 

Once a job has been entered in a batch job queue, you can monitor its status with 
the SHOW ENTRY command or the SHOW QUEUE command. For example: 

$ SUBMIT EXCHAN.DAT 

Job EXCHAN (queue SYS$BATCH entry 999) started on SYS$BATCH 
$ SHOW ENTRY 999 
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Entry Jobname 

Username 

Blocks Status 

999 EXCHAN 

On batch queue 

BLASS 

SYS$BATCH 

3 Executing 


$ SOBMIT/NOPRINTER/PARAMETER=STATS . DAT UPDATE 

Job UPDATE (queue SYS$BATCH entry 1080) started on BOSTON_BATCH 

$ SHOW QUEUE BOSTON_BATCH 

Batch queue BOSTON_BATCH on BOSTON:: 

Entry Jobname Username Blocks Status 


1080 UPDATE ODONNELL 36 Executing 

If you have no jobs in the queue, the system displays the following message: 

S SHOW QUEUE BOSTON_BATCH 

Batch queue BOSTON_BATCH, on BOSTON:: 

To see complete information on your jobs, use the /FULL qualifier with the SHOW 
ENTRY or SHOW QUEUE command, as follows: 

$ SHOW ENTRY/FULL 999 

Entry Jobname Username Blocks Status 


999 EXCHAN BLASS 3 Executing 

On batch queue BOSTON_BATCH 
Submitted ll-DEC-1994 13:12 /PRIORITY=100 
WRKD: [BLASS] EXCHAN.DAT; 3 

$ SHOW QUEUE/FULL BOSTON_BATCH 

Batch queue BOSTON_BATCH, on BOSTON:: 

/BASE_PRIORITY=3 /JOB_LIMIT=5 /OWNER= [EXEC] /PROTECTION= (S : E, 0 : D, G : R, W: W) 

Entry Jobname Username Blocks Status 


1080 UPDATE ODONNELL 36 Executing 

Submitted ll-DEC-1994 10:46 /KEEP /PARAM= ( "STATS .DAT" ) /NOPRINTER /PRIO=4 
_BOSTON$DQA2 : [ODONNELL] TEMP .COM; 1 (executing) 

The /FULL qualifier displays statistics about BOSTON_BATCH and 
characteristics associated with your job. 

To see the status of other jobs in the queue, use the SHOW QUEUE/ALL 
command as in this example: 


$ SHOW QUEUE/ALL BOSTON_BATCH 
Batch queue BOSTON_BATCH on BOSTON:: 


Entry 

Jobname 

Username 

Status 

923 

no privilege 


Executing 

939 

no privilege 


Holding until ll-DEC-1994 19:00 

1080 

UPDATE 

ODONNELL 

Executing 


Note that, unless you are a privileged user, your information is limited to jobs 
submitted under your account. See the Open VMS DCL Dictionary for more 
information on the SHOW ENTRY and SHOW QUEUE commands. 


Deleting and Stopping Batch Jobs 

You can delete batch jobs before or during execution. To delete an entry that 
is pending or already executing in a batch queue, use the DELETE/ENTRY 
command. For example, the following command deletes a job in SYS$BATCH : 

$ DELETE/ENTRY=210 SYS$BATCH 
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You need special privileges to delete a job that you did not submit. See the 
OpenVMS DCL Dictionary for more information. 

When a job terminates as a result of a DELETE/ENTRY command, the log file is 
neither printed nor deleted from your directory. 

When you terminate a job using the DELETE/ENTRY command, it is handled as 
an abnormal termination because the operating system's normal job termination 
activity is preempted. As a result, the batch job log does not, for example, 
contain the standard logout message that summarizes job time and accounting 
information. Termination that results either from an explicit EXIT command or 
STOP command or the implicit execution of either of these commands (as the 
result of the current ON condition), however, is considered normal termination. 
The operating system performs proper rundown and accounting procedures after 
a normal termination. 

Restarting a Batch Job 

If the system fails while your batch job is executing, your job does not complete. 
When the system recovers and the queue is restarted, your job is aborted and the 
next job in the queue is executed. However, by specifying the /RESTART qualifier 
when you submit a batch job, you indicate that the system should reexecute your 
job if the system fails before the job is finished. 

By default, a batch job is reexecuted beginning with the first line. See Chapter 15 
for more information about symbols you can add to your command procedures to 
specify a different restarting point. 

In addition to restarting a job after a system failure, you can also restart a job 
after you explicitly stop the job. To stop a job and then restart it on the same 
or a different queue, use the STOP/QUEUE/REQUEUE/ENTRY command. For 
example: 

$ STOP/QUEUE/REQUEUE/ENTRY=212 sys$batch 

This command stops job 212 on SYS$BATCH and requeues it on SYS$BATCH. 
(To enter this command, job 212 must have been submitted using the /RESTART 
qualifier to the SUBMIT command.) When the batch job executes the second 
time, the system uses the global symbol BATCH $RESTART to determine where 
to begin executing the job. 

17.5.6 Synchronizing Batch Job Execution 

You can use the SYNCHRONIZE and WAIT commands within a command 
procedure to place the procedure in a wait state. The SYNCHRONIZE command 
causes the procedure to wait for the completion of a specified job. The WAIT 
command causes the procedure to wait for a specified period of time to elapse. 

For example, if two jobs are submitted concurrently to perform cooperative 
functions, one job can contain the following command: 

$ SYNCHRONIZE BATCH25 

After this command is executed, the command procedure cannot continue 
execution until the job identified by the job name BATCH 25 completes execution. 
Figure 17-1 shows an example of command procedures that are submitted 
for concurrent execution but must be synchronized for proper execution. Each 
procedure compiles a large source program. 
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Figure 17-1 Synchronizing Batch Job Execution 


$ SUBMIT MAINCOMP 

JOB 314 entered on queue SYS$BATCH Q 
$ SUBMIT MINCOMP 

JOB 315 entered on queue SYS$BATCH 


DBA1 :[HIGGINS] MAINCOMP.COM 


$ FORTRAN JOBA/LIST 

© $ SYNCHRONIZE MINCOMP 

$ LINK/MAP /FULL JOBA, JOBB 
$ EXIT 


DBA1 :[HIGGINS] MINCOMP.COM 


$ FORTRAN JOBB/LIST 
$ EXIT 


ZK-0832-GE 

1 Individual SUBMIT commands are required to submit two separate jobs. The 
first process is created. 

2 After the FORTRAN command is executed, the SYNCHRONIZE command is 
executed. If job 315 is either current or pending, job 314 will not execute the 
next command. 

3 If job 315 has completed execution, job 314 continues with the next command. 

If you specify a job name with the SYNCHRONIZE command, the jobs to be 
synchronized must have the same group number in their user identification codes 
(UlCs). To synchronize jobs that have different group numbers, you must specify 
the job entry number with the SYNCHRONIZE command rather than the job 
name. For example: 

$ SYNCHRONIZE/ENTRY=454 

This SYNCHRONIZE command places the current command procedure in a wait 
state until job 454 completes. 

The WAIT command is useful for command procedures that must have access to 
a shared system resource such as a disk or tape drive. The following example 
shows a procedure that requests the allocation of a tape drive: 

$ TRY: 

$ ALLOCATE DM: RK: 

$ IF $ STATUS THEN GOTO OKAY 

$ WAIT 00:05 

$ GOTO TRY 

$ OKAY: 

$ REQUEST/REPLY/TO=DISKS - 

"Please mount BACK_UP_GMB on ' ' F$TRNLNM ( "RK" ) ' " 


If the WAIT command does not complete successfully, the procedure places itself 
in a wait state. After a 5-minute interval, it retries the request. 

The IF command following the ALLOCATE request checks the value of $STATUS. 
If the value of $STATUS indicates successful completion, the command procedure 
continues. Otherwise, the procedure executes the WAIT command; the WAIT 
command specifies a time interval of five minutes. After waiting five minutes, the 
next command, GOTO, is executed and the request is repeated. This procedure 
continues looping and attempting to allocate a device until it succeeds or until the 
batch job is deleted or stopped. 
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Security: Controlling Access to Resources 


This chapter describes some of the ways OpenVMS protects and audits your 
system resources. Some ways you can familiarize yourself with these features 
are: 


• Know the rights identifiers associated with your process— Rights identifiers 
determine what resources you can access. If your process does not have the 
appropriate identifiers, you may be unable to access certain protected objects. 

See Section 18.1 for information on displaying your rights identifiers. 

• Display security profiles of protected objects— A security profile contains 
information about protected objects. You can change the security profile of 
objects that you own to make them accessible or inaccessible to other users. 

See Section 18.2 for information on security profiles. 

• Know how to access files across networks— This can be accomplished by using 
access control strings or proxy login accounts. 

See Section 18.3 for information on accessing remote files. 

• Audit access to your account and files— This can be accomplished by closely 
observing any login messages and by working in conjunction with your 
system manager to audit your files. 

See Section 18.4 for information on auditing access to your account and files. 

For additional information on protecting objects and system security, in general, 
see the OpenVMS Guide to System Security. 


18.1 Displaying the Rights Identifiers of Your Process 

All processes that attempt to access protected objects carry credentials known 
as rights identifiers. All protected objects list a set of access requirements that 
specify who has a right to access the object in a given manner; if an accessing 
process' rights identifiers do not match those of the object, access is denied. 

You can display the identifiers for your current process with the SHOW PROCESS 
command, for example: 


$ SHOW PROCESS/ALL 

25-JUN-1991 15:23:18.08 User: GREG 

Node: ACCOUNTS 


Terminal : 

User Identifier: 
Base priority: 
Default file spec: 


TWA2 : 

[DOC, GREG] 1 
4 

W0RK1 : [GREG . FISCAL_91 ] 


Devices allocated: ACCOUNTS $TWA2 : 


Process ID: 34200094 

Process name: "_TWA2 : " 
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Process Quotas: 


Process rights: 

INTERACTIVE 2 
LOCAL 3 

SALES 4 

MINDCRIME resource 5 

System rights: 

SYS$NODE_ACCOUNTS 6 

There are three types of rights identifiers: UIC, environmental, and general. 
Output from the SHOW PROCESS command displays all three: 

1 UIC identifier, indicating user Greg is a member of the DOC group 

2 Environmental identifier, indicating user Greg is an interactive user 

3 Environmental identifier, indicating user Greg is logged in locally 

4 General identifier, indicating user Greg is also a member of the SALES group 

5 General identifier, indicating Greg holds the M I NDCRI ME identifier with the 
resource attribute so he can charge disk space to the identifier 

6 Environmental identifier, indicating user Greg is working from the 
ACCOUNTS node 

18.2 Security Profile of Objects 

Because the operating system supports many users simultaneously, it has built- 
in security mechanisms to prevent one user's activities from interfering with 
another's. Protection codes, access controls, and hardware design together protect 
the use of memory, shareable devices, and data so many users can share the 
system. An object's security profile is comprised of the user identification code 
(UIC), the ACL, and the protection codes assigned to that object. You can display 
or modify the security profile of any object that you own. 

18.2.1 Displaying a Security Profile 

To see the security profile of any protected object, use the DCL command SHOW 
SECURITY. For example, the following command requests security information 
about the file 95_FORECAST.TXT: 

$ SHOW SECURITY 95_FORECAST.TXT 

W0RK_DISK$: [GREG195_FORECAST.TXT;! object of class FILE 
Owner: [ACCOUNTING, GREG] 

Protection: (System: RWED, Owner: RWED, Group: RE, World) 

Access Control List: <empty> 

The display indicatesthefile95_FORECAST.TXT is owned by user Greg. It also 
lists the file's protection code, which gives read, write, execute, and delete access 
to system users and to the owner. The code grants read and execute access to 
group users and provides no access to world users. (See Section 18.2.3 for further 
explanation.) There is no ACL on the file. 
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18.2.2 Modifying a Security Profile 

You can provide new values for the owner, protection code, or ACL of a protected 
object, or you can copy a profile from one object to another by using the SET 
SECURITY command. 

For example, the SHOW SECURITY display in Section 18.2.1 shows the file 
95_FORECAST.TXT is owned by user Greg. As owner, he can change the 
protection code for that file. Originally, the code gave no access to users in the 
world category. Now, Greg has changed that to allow read and write access to 
world users: 

S SET SECURITY/PROTECTION= (W : RW) 95_FORECAST.TXT 

The SHOW SECURITY command verifies the new protection code for the file: 

$ SHOW SECURITY 95_FORECAST.TXT 
95_FORECAST.TXT object of class FILE 
Owner: [GREG] 

Protection: (System: RWED, Owner: RWED, Group: RE, World: RW) 

Access Control List: <empty> 

18.2.3 Interpreting Protection Codes 

A protection code controls the type of access allowed (or denied) to a particular 
user or group of users. It has the following format: 

[category: list of access allowed (, category: list of access allowed,...)] 

where the elements are as follows: 

category Includes system (S), owner (O), group (G), and world (W). Each category 
can be abbreviated to its first character. Categories have the following 
definitions: 

System Any user process or application whose UIC is in the range 1 
through 10 (octal), has SYSPRV privilege, or is in the same 
group as the owner and holds GRPPRV. 

Owner Any user process or application whose UIC is identical to the 
UIC of the object. 

Group Any user process or application whose group UIC is identical to 
the group U I C of the object. 

World Any user process or application on the system. 

When specifying more than one user category, separate the categories with 
commas and enclose the entire code in parentheses. You can specify user 
categories and access types in any order. 

A null access specification means no access, so when you omit an access 
type for a user category, that category of user is denied that type of access. 
To deny all access to a user category, specify the user category without any 
access types. Omit the colon after the user category when you are denying 
access to a category of users. 
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access-list For files, include read (R), write (W), execute (E), or delete (D). The access 
type is assigned to each ownership category and is separated from its access 
types with a colon (:). File access types have the following meanings: 

Read Gives you the right to read, print, or copy a disk file. With 

directory files, read access gives you the right to read or list a 
file and use a file name with wildcard characters to look up files. 
Read access implies execute access. 

Write Gives you the right to write to or change the contents of a 
file, but not delete it. Write access allows modification of the 
file characteristics that describe the contents of the file. With 
directory files, write access gives you the right to make or delete 
an entry in the catalog of files. 

Execute Gives you the right to execute a file that contains an executable 
program image or DCL command procedure. With a directory 
file, execute access gives you the right to look up files whose 
names you know. 

Delete Gives you the right to delete the file. To delete a file, you must 
have delete access to the file and write access to the directory 
that contains the file. 

18.2.4 Default File Protection 

A new file receives the default UlC-based protection and the default access 
control list (ACL) of its parent directory. An ACL is a collection of entries that 
define the access rights a user or group of users has to a particular protected 
object such as file, directory, or device. 

You can use either of the following methods to override the default UlC-based 
protection given to new files: 

• Default UIC protection 

The operating system provides each process with the following UlC-based 
protection: 

(S : RWED, 0 : RWED, G:RE, W) 

By default, users with a system UIC and the owners of objects have full 
access to the object, users in the same UIC group as the object owner have 
read and execute access to the object, and all other users are denied access to 
the object. To change the default protection for files that you create, enter the 
SET PROTECTION command with the /DEFAULT qualifier. For example, if 
you enter the following command in your login command procedure, you grant 
all processes read and execute access to any files that you create. (Remember 
that you must execute the login command procedure for this command to 
execute.) 

$ SET PROTECTION = (S : RWED, 0 : RWED, G : RE, W: RE) /DEFAULT 

• Default ACL protection 

You can override default UIC protection for specified directories or 
subdirectories by placing a default protection ACE in the ACL of the 
appropriate directory file. The default protection specified in the ACE is 
applied to any new file created in the specified directory or subdirectory of 
the directory. The following ACE, which must be in the ACL of a directory 
file, specifies that the default protection for that directory and the directory's 
subdirectories allow system and owner processes full access, group processes 
read and execute access, and world users no access. 
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$ SET SECURITY/ACL = (DEFAULT_PROTECTION, S :RWED, 0:RWED, G:RE, W: ) 

[JONES] PERSONAL. DIR 

To specify a default identifier ACE to be copied to the ACL of any file 
subsequently created in the directory, specify the DEFAULT option in the 
directory file's identifier ACL. For example, the following ACE, applied to a 
directory file, denies network users access to all files created in the directory: 

$ SET SECURITY/ACL = ( IDENTIFIER=NETWORK, OPTIONS=DEFAULT, ACCESS=NONE) - 
_$ [JONES] PERSONAL. DIR) 

A renamed file's protection is unchanged. A new version of an existing file 
receives the UlC-based protection and ACL of the previous version. (Use the 
/PROTECTION qualifier of the BACKUP, COPY, CREATE, and SET FILE 
commands to override the default U I C-based protection.) 

18.2.5 Explicit File Protection 

You can explicitly specify UlC-based protection for a new file with the 
/PROTECTION qualifier (valid with the BACKUP, COPY, and CREATE 
commands) as shown in the following example: 

$ CREATE MAST12 . TXT/PR0TECTI0N= (S : RWED, 0 : RWED, G, W) 

You can change the UlC-based protection on an existing file with the SET 
SECURITY/PROTECTION command. For example, to change the UlC-based 
protection on the file MAST12.TXT, enter the following command: 

$ SET SECURITY/PROTECTION=(S: RWED, 0: RWED, G: RE, W) MAST12.TXT 

After a file is created and you have created an ACL for the file, you can modify 
the ACL and add as many entries to the ACL as you want. The protection 
specified by the ACL overrides the file's user identification code protection. 

18.3 Accessing Files Across Networks 

This section describes how to use access control strings and proxy logins to access 
files on remote systems. 

18.3.1 Protecting Information in Access Control Strings 

Network access control strings can be included in the file specifications of DCL 
commands working across the DECnet for OpenVMS network. They permit a 
user on a local node to access a file on a remote node. 

An access control string consists of the user name for the remote account and the 
user's password enclosed within quotation marks, as follows: 

NODE"username password": :disk:[directory]filename.filetype 

Because access control strings include sufficient information to allow someone to 
break in to the remote account, they create serious security exposure. To protect 
access control string information, do the following: 

• Avoid revealing the information on either hardcopy or video terminals. If you 
use a hardcopy terminal, dispose of the output properly. If you use a video 
terminal, clear the screen and empty the recall buffer with the DCL command 
RECALL/ERASE when the network job is completed. This prevents another 
user from seeing the password, either by displaying the command line with 
the Ctrl/B sequence or with the DCL command RECALL/ALL. 

• Do not place networking commands that include access control strings in 
command procedures where they would be likely targets for discovery. 
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• If you must put access control strings in your command procedures, provide 
these files with optimum file protection. 

To avoid the need for access control strings, you might prefer to use proxy login 
accounts, which are described in Section 18.3.2. 

18.3.2 Using Proxy Login Accounts to Protect Passwords 

Proxy logins let you access files across a network without specifying a user name 
or password in an access control string. Thus, proxy logins have the following 
security benefits: 

• Passwords are not echoed on the terminal where the request originates. 

• Passwords are not passed between systems where they might be intercepted 
in unencrypted form. 

• Passwords are not needed in command files to perform the remote access 
steps. 

Before you can initiate a proxy login, the system or security administrator at the 
remote node must create a proxy account for you. Proxy accounts, like regular 
accounts, are created with theOpenVMS Authorize utility (AUTHORIZE). They 
are usually nonprivileged accounts. Security administrators can allow you access 
to one default proxy account and up to 15 other proxy accounts. While proxy 
logins require more setup effort on the part of system managers, they provide 
more secure network access and eliminate the need for users to enter access 
control strings. 

The following examples illustrate the differences between a normal network login 
request and a proxy login request. For each example, the following conditions 
exist: 

• The user K MAHOGANY has two user accounts: 

- An account on node BIRCH with the password "XYZ123ABC" 

- An account on node WALNUT with the password "A25D3255" 

• KMAHOGANY has logged in to node BIRCH. 

• KMAHOGANY wants to copy the file BIONEWS. MEM from the default 
device and directory of the account on the node WALNUT. 

The following diagram illustrates these conditions: 

At Home Node Remote Node 

BIRCH WALNUT 


Username: KMAHOGANY Username: KMAHOGANY 

Password: XYZ123ABC Seeks from ^ Password: A25D3255 


STAFFDEV: [ KMAHOGANY] 


STAFFDEV: [ KMAHOGANY] 


A copy of the file 


BIONEWS. MEM 


ZK-2036-GE 
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The user KMAHOGANY could use an access control string to copy the file 
BIONEWS. MEM, as follows: 

$ COPY WALNUT "KMAHOGANY A25D3255" : :BI0NEWS .MEM BIONEWS. MEM 

Notice that the password A25D3255 echoes. Anyone who observes the screen can 
see it. I n contrast, if KMAHOGANY has proxy access from node Bl RCH to the 
account on node WALNUT, the command for copying the file BIONEWS. MEM is 
as follows: 

$ COPY WALNUT: : BIONEWS. MEM BIONEWS. MEM 

KMAHOGANY does not need to specify a password in an access control string. 

I nstead, the system performs a proxy login from her account on node Bl RCH into 
her account on node WALNUT. There is no exchange of passwords. 

Using a General Access Proxy Account 

Your security administrator can also authorize groups of users from foreign nodes 
to share in the use of a general access proxy account. For example, the security 
administrator at node WALNUT can create a general access account with the 
following conditions: 

• The user name GENACCESS. 

• Access limited to network logins. 

• A password known only to the owner of the account. (None of the remote 
users need to know it.) This helps to protect the account. 

• The default device and directory STAFFDEV:[BIOSTAFF], 

If the security administrator grants Bl RCH ::KM AHOGANY proxy access to the 
GENACCESS account, the user KMAHOGANY can copy the file BIONEWS. MEM 
by entering the following command: 

$ COPY WALNUT: : [KMAHOGANY] BIONEWS. MEM BIONEWS. MEM 

Note that KMAHOGANY must specify the directory [KMAHOGANY] because 
the file BIONEWS. MEM is not in the default device and directory for the 
GENACCESS account (STAFFDEV:[BI OSTAFF]). In addition, the protection 
for the file BIONEWS. MEM must permit access to the GENACCESS account. 
Otherwise, the command fails. 

When You Need to Specify the Name of a Proxy Account 

If you have access to more than one proxy account on a given node and you do 
not want to use the default proxy account, specify the name of the proxy account. 
For example, to use a proxy account called PROXY2 instead of the GENACCESS 
account (the default), KMAHOGANY enters the following command: 

$ COPY WALNUT "PR0XY2" :: [KMAHOGANY] BIONEWS. MEM BIONEWS. MEM 

This command uses the PROXY 2 account to copy the file Bl ONEWS.M EM from 
the [KMAHOGANY] directory on node WALNUT. 

18.4 Auditing Access to Your Account and Files 

Although it is the security administrator's job to monitor the system for possible 
break-in attempts, you can assist the security administrator in auditing access to 
your account and files. 


18-7 


Security: Controlling Access to Resources 
18.4 Auditing Access to Your Account and Files 

This section describes how to monitor your last login time for possible break-ins. 
It also describes how to work with your security administrator to enable certain 
types of auditing. 

18.4.1 Observing Your Last Login Time 

The OpenVMS system maintains information in your UAF record about the last 
time you logged in to your account. Your security administrator decides whether 
the system should display this information at login time. Sites with medium to 
high security requirements frequently display this information and ask users 
to check it for unusual or unexplained successful logins and unexplained failed 
logins. 

If there is a report of an interactive or a noninteractive login at a time when 
you were not logged in, report it promptly to your security administrator. Also 
change your password. The security administrator can investigate further by 
using accounting files and audit logs. 

If you receive a login failure message and cannot account for the failure, it is 
likely that someone has been trying to access your account unsuccessfully. Check 
your password to ensure that it adheres to all recommendations for password 
security described in Section 2.8. If not, change your password immediately. 

If you expect to see a login failure message and it does not appear or if the count 
of failures is too low, change your password. Report either of these indications of 
login failure problems to your security administrator. 

18.4.2 Asking Your Security Administrator to Enable Auditing 

The security administrator can select one or more types of events that warrant 
special attention when they occur. When such an event is detected, the security 
administrator directs the system to send an audit to the system security audit 
log file or an alarm to terminals enabled as security operator terminals. For 
example, the security administrator might identify one or more files for which 
write access is prohibited. An audit can be enabled or an alarm can be set to 
indicate attempted access to these files. 

Events triggering an audit or alarm can include the following: 


Example of Events Initiating Security Audits or Alarms 


Installation of images 
Certain types of file access 

Volume mounts and dismounts 

Access event requested by an ACL 
file or global section 


Modifications to: 

• System and user passwords 

• System authorization file 

• Network proxy file 

• Rights database 

Logins, logouts, login 

failures, break-in attempts 


If you suspect a break-in to your account, change your password. You might want 
to request that your security administrator implement auditing on sensitive files. 
For example, assume you decide to audit the file CON F I DR E VI EW.MEM . If user 
ABADGUY accesses CON FI DREVI EW.MEM and has delete access, the following 
audit record is written to the system security audit log file: 
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00000000000 


OPCOM ll-DEC-1994 09:21:11.10 


00000000000 


Message from user AUDIT$SERVER on BOSTON 

Security audit (SECURITY) on BOSTON, system id: 19424 

Auditable event: Attempted file access 


Event time: 

PID: 

Username : 

Image name : 

Object name: 
Object type: 
Access requested: 
Status : 

Privileges used: 


ll-DEC-1994 09:21:10.84 
23E00231 
ABADGUY 

BOSTON$DUAO : [SYSO . SYSCOMMON. ] [SYSEXE] DELETE . EXE 

_B0ST0N$DUA1 : [RWOODS] CONFIDREVIEW.MEM; 1 

file 

DELETE 

%SYSTEM-S-NORMAL, normal successful completion 
SYSPRV 


The auditing message reveals the name of the perpetrator, the method of access 
(successful deletion accomplished by using the program [SYSEXEJDELETE.EXE), 
time of access (9:21 a.m.), and the use of a privilege (SYSPRV) to gain access to 
the file. With this information, the security administrator can take action. 

Note that the security audit message is written to the security audit log file 
every time any file is accessed and meets the conditions specified in the 
audit entry of the ACL for that file (see Section 18.4.3). Access to the file 
CONFIDREVIEW.MEM, as well as access to any file on the system that is 
protected with security auditing, prompts an audit record to be written to the 
security audit log file. 

After auditing has been introduced, check with your security administrator 
periodically to see if any additional break-ins have occurred. 


18.4.3 Adding Access Control Entries to Sensitive Files 

If you have key files that might have been accessed improperly, you might want 
to develop a strategy with your security administrator to audit access to the files. 

Once you review the situation and ensure that you have done everything possible 
to protect your files with standard protection codes and general ACLs (described 
in the OpenVMS Guide to System Security), you may conclude that security 
auditing is required. 

To specify security auditing, you can add special access control entries (ACEs) to 
files you own or to which you have control access. Keep in mind, however, that 
the audit log file is a systemwide mechanism, so Digital recommends that a site 
security administrator control the use of file auditing. Although you can add 
auditing ACEs to files over which you have control, the security administrator 
has to enable auditing of files on a system level. 

If you suspect break-in attempts to your account, the security administrator may 
temporarily enable auditing for all file access. The security administrator can 
also enable auditing to monitor read access to your files to catch file browsers. 

For example, if user RWOODS and his security administrator concur that 
they must know when a highly confidential file, CONFIDREVIEW.MEM, is 
being accessed, RWOODS can add an entry to the existing ACL for the file 
CONFIDREVIEW.MEM, as follows: 

$ SET SECURITY/ACL= (ALARM=SECURITY, ACCESS=READ+WRITE- 
_$ +DELETE+CONTROL+FAILURE+SUCCESS) CONFIDREVIEW.MEM 

An access violation of one file frequently indicates access problems with other 
files. Therefore, the security administrator may need to monitor access to all key 
files having security-auditing ACEs. When undesired access is gained to key files, 
the security administrator must take immediate action. 
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Customizing EVE 


This appendix describes how to use startup files to modify the standard EVE 
editor. Startup files hold key definitions and editing commands that set the 
characteristics of the editing environment. Startup files can also hold DECTPU 
procedures, which augment the editing capability of the standard EVE editor. 

By placing your definitions and procedures in a startup file, you can invoke the 
editor and automatically establish the editing environment your task requires. 
The following sections describe how to create and use different types of startup 
files. 

A.1 Creating a Customized Editor 

EVE provides the following ways of tailoring the standard editor to meet your 
editing requirements: 

• Defining editing keys 

You can assign an editing command to a key so that commands are faster to 
enter. For example, you can bind the EVE command ERASE WORD to the 
key sequence Ctrl/D. 

• Creating learn sequences 

You can assign a series of commands or keystrokes to one key. For example, 
you can create a learn sequence where you can press one key to insert a new 
phone number into a standard memo heading. 

• Using the DEC Text Processing Utility (DECTPU) to write editing procedures 

Because EVE is built on a powerful, programmable utility called the DEC 
Text Processing Utility, you can expand the editor beyond its standard 
set of commands by using DECTPU procedures. With DECTPU language 
statements, you can write procedures that create features that are not 
available in standard EVE. For example, you can write a procedure to 
transpose two characters and assign this procedure to a key. 

A.2 Defining EVE Keys 

You can define keys to execute EVE commands or to enter a series of keystrokes, 
called a learn sequence. 

EVE does not let you define the Return key (Ctrl/M), the space bar, or any 
printing characters (such as letters, digits, and punctuation marks) on the main 
keyboard. 

In addition, Digital recommends that you do not define the following keys and 
control key sequences (some cannot be defined unless you use special terminal 
settings): 
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Break 

Delete or <3 
Escape or Ctrl/[ 

FI to F 6 (VT200 and VT300 series terminals) 

H el p (PF2 on VT100 series terminals) 

N oscrol I 

Shift 

Ctrl/C 

Ctrl/I (Tab key) 

Ctrl/O 

Ctrl/Q 

Ctrl/R (which EVE defines as REMEMBER) 

Ctrl/S 

Ctrl/T 

Ctrl/U (which EVE defines as START OF LINE) 

Ctrl/X 

Ctrl/Y 

You can define all other keys, including control keys. You can redefine the Do key, 
as long as you have assigned the DO command to another key. 

The SET SHIFT KEY and SET NOSHIFT KEY commands are obsolete. Instead, 
use the SET GOLD KEY and SET NOGOLD KEY commands, respectively. For 
more information about setting a GOLD key, see Section A. 2. 3. 

A.2.1 Defining Keys to Execute EVE Commands 

By defining keys, you can create editing keys to enter EVE commands you use 
frequently. You can define a key to execute an EVE command by using the 
DEFI NE KEY command or by using an initialization file. If you are using help 
and press a key to which you have assigned an EVE command, EVE provides 
the help text for that command. Key definitions are discarded when you end an 
EVE editing session, unless you use the SAVE ATTRIBUTES command or SAVE 
EXTENDED EVE command to save key definitions from one editing session to 
the next. 

The DEFI NE KEY command assigns an EVE command to a single key, a GOLD 
key combination, or control key sequence. You can enter the DEFINE KEY 
command, the key to be defined, and the command on a single command line, or 
you can enter the DEFINE KEY command and let EVE prompt you. 

To enter the DEFI NE KEY command on a single command line, use the following 
command syntax: 

DEFINE KEY [=key-name] command 
The elements are as follows: 
key-name The key to be defined 

command The command to assign to the key 

For example, the following command assigns the MOVE BY WORD command to 
keypad key 1 (KP1): 

Command: DEFINE KEY=KP1 MOVE BY WORD 

The following command assigns the FILL command to Ctrl/F : 

Command: DEFINE KEY=Ctrl/F FILL 
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You can use one of three different separators when specifying key names: an 
underscore, a hyphen, or a slash. For example, the Ctrl/F key can be specified as 
CtrI F, Ctrl-F, or Ctrl/F. 

To use the DEFINE KEY command and let EVE prompt you, invoke EVE, then 
press the Do key and enter the DEFINE KEY command, as follows: 

[End of file] 

Buffer: MAIN | Write | Insert | Forward 

Command: DEFINE KEY 

Type the EVE command you want to assign to a key and press the Return key. 

[End of file] 

Buffer: MAIN | Write | Insert | Forward 

EVE command: START OF LINE 

Press the key to be associated with the EVE command. 

[End of file] 

Buffer: MAIN | Write | Insert | Forward 

Press the key you want to define: |F 2 o[ 

The message "Key defined" appears if you have successfully defined a key. 

Another way to assign EVE commands to keys is to create an initialization 
file. You can define keys and set the characteristics of an editing session in the 
initialization file. The file contains EVE commands and key definitions, and 
is executed when you invoke EVE. Use the syntax given in this section to put 
DEFINE KEY commands in the file. For more information about initialization 
files, see the online help topic called I nitialization Files. 

To remove a key definition, use the UN DEFINE KEY command. 

Section A. 2. 3 contains more examples of defining keys to execute EVE commands. 

You can type the name of a key as a parameter for the DEFI NE KEY, SET 
GOLD KEY, SHOW KEY, and UNDEFINE KEY commands. EVE key names 
are generally the same as the labels on the keys— you can specify them by their 
labels as well as by their positional number on one of the keypads. For example, 
the 7 on the numeric keypad is named KP7 and the keys on the mini keypad are 
named El to E 6. 

You can abbreviate key names as long as your abbreviation is not ambiguous. 

For example, G Rem is a valid abbreviation for GOLD Remove and G R is an 
abbreviation for GOLD R. The case of letters does not matter in a key definition. 

You can specify control keys by using Ctrl, Control, or the circumflex character 
(~). For example, Ctrl/A, Control/A, and 'TV are the same. For a list of the control 
keys defined by EVE, see the EVE online help topic called Control Keys. 

In specifying control keys or GOLD key sequences, use a hyphen, slash, or 
underscore as a delimiter in the key name (for example, Alt/A, Ctrl_N, or 
GOLD-F20.) Thus, in an initialization file, you can use commands with typed key 
names such as the following: 

DEFINE KEY= Ctrl/P MOVE BY PAGE 
DEFINE KEY= GOLD-N NEXT BUFFER 
DEFINE KEY= KP7 CENTER LINE 
SET GOLD KEY F17 
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Some EVE key names are different from key names that you use in DECTPU 
command files, as shown in Table A-l. 


Table A-1 Key Name Differences Between EVE Commands and DECTPU 
Procedures 


In EVE Commands 

In DECTPU Procedures 

GOLD A 

KEY_NAM E (A, SHI FT_KEY) 

GOLD MINUS 

KEY_NAME (MINUS, SHIFTJCEY) 

Ctrl/D 

Ctrl_D KEY 

SHIFT/F14 

KEYJMAME (F14, SH 1 FT_MODI F 1 E D) 


Table A-2 lists EVE key names and the key labels on the keyboard or keypads. 
Some keys may not appear on some terminals. (For example, VT100 series 
terminals do not have the FI to F20 keys. VT200 , VT300, and VT400 series 
terminals do not have Backspace and line-feed keys.) 


Table A-2 EVE Key Names 

Key Key Name 1 


F7 . . . F20 

F7 . . . F20 

Help 

HELP or F15 

Do 

DO or F 16 

Find 

FIND or El 

1 nsert Here 

INSERTJHERE or E2 

Remove 

REMOVE or E3 

Select 

SELECT or E4 

Prev Screen 

PREV_SCREEN or E5 

Next Screen 

NEXT_SCREEN or E6 

t (up arrow) 

UP 

<- (left arrow) 

LEFT 

| (down arrow) 

DOWN 

-> (right arrow) 

RIGHT 

PF1 . . . PF4 

PF1 . . . PF4 

0 . . . 9 (numeric keypad) 

KPO . . . KP9 

- (numeric keypad) 

MINUS 

. (numeric keypad) 

PERIOD 

, (numeric keypad) 

COMMA 

<3 or Delete 

DELETE 

Tab or TAB 

TAB or Ctrl/I 


1 Do not use these key names in DECTPU built-in procedures. See the table "Keywords Used for Key 
Names" in the Guide to the DEC Text Processing Utility for the correct keywords to use in DECTPU 
built-in procedures. 


(continued on next page) 
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Table A-2 (Cont.) EVE Key Names 


Key 

Key Name 1 

Backspace 

BS or Ctrl/H 

L i ne-feed 

LF or Ctrl/J 

1 Do not use these key names in DECTPU built-in procedures. See the table "Keywords Used for Key 
Names" in the Guide to the DEC Text Processing Utility for the correct keywords to use in DECTPU 
built-in procedures. 


A.2.2 Nondefinable Keys 

You cannot define any of the following keys: 

F 1 to F 6 

Compose Character 
Ctrl (by itself) 

Return or Ctrl-M 
Break 

Escape or Ctrl/[ 

Lock or Caps Lock 
No Scroll 
sit-up 
Shift 

In addition, EVE does not let you define typing keys on the main keyboard 
(except in combination with a modifier), a key defined as DO if it is the only key 
defined as DO, or the key currently set as GOLD, if any. 

Digital recommends that you do not define the following keys and control keys. 
You can define these control keys, but you cannot execute them unless you set 
terminal characteristics in special ways. 

Delete or <S (which EVE defines as DELETE) 

Help or on VT100 terminals, PF2 
Ctrl/B (which EVE defines as RECALL) 

Ctrl/C 

Ctrl/O 

Ctrl/Q 

Ctrl/R (which EVE defines as REMEMBER to end a learn sequence) 

Ctrl/S 

Ctrl/T 

Ctrl/U (which EVE defines as ERASE START OF LINE) 

Ctrl/V (which EVE defines as QUOTE) 

Ctrl/X 

Ctrl/Y 

If you redefine Ctrl/B or Ctrl/R, you should define other keys as RECALL and 
REMEMBER, respectively, because you can execute those commands only by 
pressi ng a key. 
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A.2.3 Defining the GOLD Key 

You can assign two definitions to the same editing key if you create a GOLD 
key. I nvoke one key definition by pressing the editing key. I nvoke the other key 
definition by first pressing the GOLD key and then pressing the editing key. 

To define a GOLD key, enter the SET GOLD KEY command and press the key 
you want to use as the GOLD key. When you successfully define the key, the 
message "GOLD key set." appears in the Messages buffer. EVE does not have a 
default GOLD key. 

After you create a GOLD key, you can use the GOLD key definitions supplied 
by EVE. To see a diagram of these key definitions, enter the command HELP 
KEYPAD. The GOLD key definitions appear in the display in reverse video. 

The following table lists the GOLD key combinations on the EVE keypad and the 
definitions associated with them: 


Key 

Definition 

GOLD F13 

Restore Word (except with the WPS keypad) 

GOLD Help 

H el p keys 

GOLD Find 

Wildcard Find 

GOLD 1 nsert Here 

Restore 

GOLD Remove 

Store Text 

GOLD Select 

Reset 

GOLD Prev Screen 

Previous Window 

GOLD Next Screen 

Next Window 

GOLD t 

Top 

GOLD | 

Bottom 

GOLD «- 

Start of Line 

GOLD -> 

E nd of L i ne 


You can also use the GOLD key to create your own key definitions. The following 
example demonstrates how to define a GOLD key and assign two commands to a 
single key. The example defines the 4 key on the numeric keypad as the GOLD 
key and then assigns the BOTTOM and TOP commands to the Ctrl/G key. Thus, 
pressing Ctrl/G alone enters the BOTTOM command and pressing the GOLD key 
followed by Ctrl/G enters the TOP command. 

To define a GOLD key and the bottom and top keys, follow these steps: 

1. Define the GOLD key: 

a. Press the Do key, type SET GOLD KEY, and press the Return key. 

b. Press the 4 key on the numeric keypad. 

2. Define the bottom key: 

a. Press the Do key, type DEFINE KEY, and press the Return key. 

b. Type BOTTOM and press the Return key. 

c. Press Ctrl/G. Ctrl/G is now defined as BOTTOM . 

3. Define the GOLD Ctrl/G key as the top key: 

a. Press the Do key, type DEFINE KEY, and press the Return key. 
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b. Type TOP and press the Return key. 

c. Press and hold down the GOLD key (4 on the numeric keypad) and press 
Ctrl/G. 

For the rest of your editing session, when you press Ctrl/G, EVE executes the 
BOTTOM command, and when you press the GOLD key (4 on the numeric 
keypad) followed by Ctrl/G, EVE executes the TOP command. If you press 
the GOLD key by mistake, press the Select key to cancel it. Use the SAVE 
ATTRIBUTES command or the SAVE EXTENDED EVE command to save key 
definitions from one editing session to the next. 

You cannot define more than one GOLD key at a time. To remove a GOLD key 
definition, enter the SET NOGOLD KEY command, then press the key you want 
to undefine. You can also define another GOLD key, which removes the original 
GOLD key. 

Use the following format to define a GOLD key in an initialization file: 

SET GOLD KEY keyname 

For example, the following command defines the PF1 key as the GOLD key: 

SET GOLD KEY PF1 

A. 2. 4 Defining Keys to Enter Learn Sequences 

The LEARN command assigns a sequence of keystrokes, called a learn sequence, 
to a single key or control key sequence. With learn sequences, you can enter the 
same series of keystrokes in a buffer any number of times by pressing one key. 

All learn sequences are discarded when you terminate an EVE editing session 
unless you use the SAVE ATTRI BUTE S command or the SAVE EXTENDED EVE 
command to save them from one editing session to the next. 

To define a learn sequence, take these steps: 

1. Enter the LEARN command. 

2. Type the keystrokes to be remembered. You can press keys already defined, 
type text, or both. 

3. Press Ctrl/R. At the prompt, press the key to be associated with the learn 
sequence, such as F17 or PF3. To cancel the learn sequence, press the Return 
key or Ctrl/M . 

The message "Key sequence remembered” appears if you have successfully defined 
a key. 

To define a learn sequence that inserts a string of text into your file when you 
press Ctrl/F, follow these steps: 

1. Invoke EVE toeditthefileRHYMES.DAT. 

She rhymes with tree, 

also with bee, 

and this one makes three. 

[End of file] 

Buffer: RHYMES.DAT | Write | Insert | Forward 

3 lines read from file WORKDISK: [USER] RHYMES .DAT 

2. Move the cursor to the end of the buffer. To begin the definition of the learn 
sequence, press the Do key, and enter the LEARN command. 
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3. I nsert the following text, which EVE is to remember, at the end of your file: 

And what is a rhyme? 

4. Press Ctrl/R. 

5. Press Ctrl/F, the key to which you are assigning the learn sequence. 

For the rest of the editing session, when you press Ctrl/F, EVE inserts the text 
"And what is a rhyme?" wherever the cursor is positioned at the time. 

A.3 Setting and Saving Attributes 

You can save most global attributes in a section file or DECTPU command file for 
future editing sessions. You can also set a default section file or command file to 
be created or updated for saving attributes. 

A.3.1 EVE Default Settings 

Table A-3 lists the EVE default settings— the settings EVE uses unless you 
specify otherwise. You may want to refer to this table to check which settings 
you want to change when creating an initialization file. Some settings are global 
(applying to all buffers you edit), and others are buffer specific. For example, the 
type of cursor motion (bound or free) and tab mode (insert, spaces, or movement) 
are the same for all buffers you edit, whereas you can set margins, paragraph 
indents, and tab stops differently for each buffer. 


Table A-3 EVE Default Global Settings for All Buffers 

Default Setting Effect 


SET BOX NOSELECT 

SET BOX PAD 
SET CURSOR FREE 


SET EXIT ATTRIBUTE CHECK 

SET FIND CASE NOEXACT 
SET FIND NOWHITESPACE 

SET FUNCTION KEYS 
NODECWI NDOWS 


Disables box-style selection, cutting, and 
pasting so you can select and edit standard 
linear ranges. 

Enables padding and overstriking for box 
editing, regardless of the mode of the buffer. 

You can move the cursor anywhere in the 
buffer and enter text there, as opposed to a 
bound cursor, which cannot move into the 
unused portion of the buffer. Using SET 
KEYPAD WPS automatically enables a bound 
cursor. 

If you changed attributes, then when you exit 
or quit, EVE asks whether you want to save 
them. 

EVE finds any occurrence of a text string if 
you enter the search string in all lowercase. 

FIND and WILDCARD FIND commands 
match spaces and tabs in the search string 
exactly as entered, and do not search across a 
line break. 

Keeps the normal key definitions (EVE 
default, EDT keypad, or WPS keypad) rather 
than defining some keys for DECwindows 
functions. 


(continued on next page) 
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Table A-3 (Cont.) EVE Default Global Settings for All Buffers 


Default Setting 

Effect 

SET KEYPAD NUMERIC 
or 

SET KEYPAD VT100 

On VT200, VT300, and VT400 series 
terminals, keys on the numeric keypad are 
undefined, except for the PF4 and Enter keys. 
On VT100 series terminals, the numeric 
keypad is used for the EVE default key 
bindings. Control keys are defined the same 
on either type of terminal. Also, you can set 
the EDT keypad or WPS keypad on either 
type of terminal. 

SET NOCLIPBOARD 

Copy, cut, and paste operations use the 1 nsert 
Here buffer in EVE. On DECwindows, you can 
enable the clipboard, which lets you transfer 
text between EVE and other DECwindows 
applications. WPS keypad keys do not use the 
clipboard, regardless of the setting. 

SET NODEFAULT COMMAND FILE 

EVE uses one of the following as the default 
command file for saving attributes: 

• Command file specified with the 
/COMM AN D= qualifier when you invoked 
EVE 

• Command file named 

TPU $COM M AN D.TPU in the current 
directory 

• A command file defined by the logical 
name TPU $COM MAN D 

SET NODEFAULT SECTION FILE 

If section file prompting is enabled (the 
default), EVE prompts whether to save 
attributes in a section file. If section file 
prompting is disabled, EVE prompts whether 
to save attributes in a command file. 

SET NOGOLD KEY 

EVE does not have a default GOLD key. 
Setting the EDT or WPS keypad makes 

PF1 the GOLD key, overriding any current 
definition of PF1, unless you set a different 
key as GOLD. 

SET NOPENDING DELETE 

Using DELETE or typing new text does not 
erase a selection. 

SET SECTION FILE PROMPTING 

When you save attributes and other 
customizations, EVE prompts for a section 
file. 

SET SCROLL MARGINS 0 0 

Scrolling begins automatically when you move 
past the top or bottom of the wi ndow. 

SET TABS INSERT 

Using TAB inserts a tab character. You can 
set the tab mode to i nsert spaces i nstead of a 
tab character, or to move the cursor without 
inserting anything. 

SETTABS INVISIBLE 

Tab characters appear during editing as blank 
spaces, as opposed to visible tabs, which 
appear as a small (horizontal tab). 

(continued on next page) 
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Table A-3 (Cont.) EVE Default Global Settings for All Buffers 


Default Setting 

Effect 

SET Wl DTH 80 

The width of the EVE screen layout is the 
same as your terminal setting— typically 80 
columns. 

SET WILDCARDS VMS 

The WILDCARD FIND command uses 
wildcards such as the asterisk (*) to match 
any amount of text on a line, the percent sign 
(%) to match a single character on a line, and 
so on. 


Table A-4 lists the EVE default settings for buffer-specific settings. 

Table A-4 EVE Default Buffer-Specific Settings 


Default Setting 

Effect 

FORWARD 

Commands like FIND and MOVE BY LINE 
move the cursor to the right and down. You 
can change the direction to reverse (left and 
up). 

INSERT MODE 

Characters you type are inserted at the 
current position, pushing existing text to 
the right and down. You can change the mode 
to overstrike. 

SET BUFFER MODIFIABLE 

Buffers you create can be modified (edited). 
You can set the buffer to unmodifiable. 

SET BUFFER WRITE 

On exiting, EVE writes out (saves) your 
buffers if you have made any changes. You 
can set the buffer to read-only. 

SET J OURNALING ALL 

Buffer-change journaling is enabled for all 
your text buffers. 

SET LEFT MARGIN 1 

This is the leftmost column. When you press 
the Return key or use FILL commands or 
when EVE wraps text, new lines start at the 
left margin of the buffer. 

SET PARAGRAPH INDENT 0 

Paragraphs you create or ones you reformat 
with FILL commands start at the current left 
margin of the buffer— with no indent. 

SET RIGHT MARGIN 79 

The default right margin is one column less 
than the width set for your terminal. If the 
width is 80 columns, the default right margin 
is 79. When you use FILL commands or when 
you type at the end of a line, EVE wraps text 
at the right margin of the buffer. 

SET TABS EVERY 8 

Tab stops are set at columns 9, 17, 25, 33, 41, 
and so on. You can set tab stops at different 
intervals. 

SET WRAP 

As you type text at the end of a line, EVE 
wraps text at the right margin of the buffer, 
without your having to press the Return key 
or use FILL commands. 


A-10 


Customizing EVE 
A.3 Setting and Saving Attributes 

Note 

When editing EVE command lines— such as when you recall a command— 
the default direction is reversed and the cursor is bound. The default 
mode on a character-cell terminal matches your terminal setting. 


You can save some EVE settings or attributes in a section file or as EVE- 
generated code in a DECTPU command file. You can set other attributes, such as 
margins and tab stops, in an initialization file. 

The following is a sample EVE initialization file that contains commands to set 
editing preferences and to define keys: 

! MYINIT.EVE initialization file 

i 

SET LEFT MARGIN 5 

SET PARAGRAPH INDENT 4 

SET RIGHT MARGIN 70 

SET TABS EVERY 10 

SET SCROLL MARGINS 9% 9% 

SET FIND WHITESPACE 
! Key definitions 
SET KEYPAD EDT 

DEFINE KEY= F20 SHOW BUFFERS 

DEFINE KEY= Ctrl/P PAGINATE 

DEFINE KEY= GOLD-G GET FILE 

DEFINE KEY= KP7 WPS GOLD R 

When you use an initialization file to invoke EVE, commands in the initialization 
file for margins, tab stops, and other buffer-specific settings apply to the Main 
(or first) buffer and to an EVE system buffer named $DEFAULTS$. The 
$DEFAULTS$ buffer is a template buffer; when you create a buffer— for example, 
by using the GET FI LE command— EVE uses the settings of the $DEFAULTS$ 
buffer so that each new buffer has the same settings. Thus, if your initialization 
file contains the command SET RIGHT MARGIN 70, each buffer you create will 
have that right margin. 

To find out the default settings, use the SHOW DEFAULTS BUFFER command. 
To find out the settings of the buffer you are editing, use the SHOW command. 

A.3.2 Saving Attributes 

Attributes are global settings, some of which can be saved in a section file or 
DECTPU command file for future editing sessions. Table A-5 shows the settings 
that you can save. 


Table A-5 EVE Commands for Setting Attributes 
Command Default Setting 


SET BOX [NO]PAD 
SET BOX [NOJSELECT 
SET [NO]CLI PBOARD 


SET BOX PAD 
SET BOX NOSELECT 
SET NOCLIPBOARD 

(continued on next page) 
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Table A-5 (Cont.) EVE Commands for Setting Attributes 


Command 

Default Setting 

SET CURSOR | BOUNI5 J 

SET CURSOR FREE 

SET [NOJDEFAULT COMMAND FILE 

SET [NOJDEFAULT SECTION FILE 

SET FIND CASE [NO]EXACT 

SET [NOJEXIT ATTRIBUTE CHECK 

SET NODEFAULT COMMAND FILE 

SET NODEFAULT SECTION FILE 

SET FIND CASE NOEXACT 

SET EXIT ATTRIBUTE CHECK 


SET [NO]SECTION FILE PROMPTING SET SECTION FILE PROMPTING 


SET [NOJPENDING DELETE 

SET NOPENDING DELETE 

f INSERT 1 

SET TABS \ MOVEMENT > 
l SPACES J 

SET TABS INSERT 

SET TABS [INVISIBLE 

SET TABS INVISIBLE 


If you have an EVE initialization file that contains commands for these settings, 
you can delete those command lines after you save the settings in your section 
file or command file. 

Other global settings (such as scroll margins or the types of wildcards) and any 
buffer settings (such as margins or tab stops) are not saved. Typically, you use an 
initialization file for those settings. 

Table A-6 summarizes the new and changed commands for saving attributes. 

Table A-6 EVE Commands for Saving Attributes 


Command 

Usage or Effect 

SAVE ATTRIBUTES 

Saves attributes in a section file or command file, 
depending on your responses to EVE prompts 
or settings done with other EVE commands. If 
you save in a section file, the effect is the same 
as SAVE EXTENDED EVE. If you save in a 
command file, EVE generates a specially marked 
block of DECTPU statements for attribute 
settings and menu definitions, and either creates 
a command file or updates an existing command 
file with this block of statements. 

SAVE SYSTEM ATTRIBUTES 

Saves EVE default attributes in a section file 
or command file. This is useful if you want to 
restore your section file or command file to the 
standard EVE settings and menu definitions (see 
Section A. 3.5). 

(continued on next page) 
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Table A-6 (Cont.) EVE Commands for Saving Attributes 


Command 

Usage or Effect 

SAVE EXTENDED EVE 

Creates a section file, saving attributes, 
key definitions, menu definitions, compiled 
procedures, and other extensions, such as global 
variables set with a DECTPU statement. If you 
do not specify a section file on the command line, 
EVE prompts you for one or uses your default 
section file (if you set a default). 

SET BOX NOPAD 

Disables padding and overstriking for box editing, 
unless the mode of the buffer is overstrike. 

SET BOX NOSELECT 

Disables box-style selection, cutting, and pasting. 
Default setting. 

SET BOX PAD 

Enables padding and overstriking for box editing, 
regardless of the mode of the buffer. Default 
setting. 

SET BOX SELECT 

SET DEFAULT COMMAND FILE 

Enables box selection, cutting, and pasting. 

Determines the command file for saving 
attributes. Does not determine the command 
file to be executed at startup, if any. 

SET DEFAULT SECTION FILE 

Determines the section file for saving attributes. 
Does not determine the section file to be executed 
at startup. 

SET EXIT ATTRIBUTE CHECK 

If you changed attributes, then when you exit or 
quit, EVE asks if you want to save your changes. 
Default setting. 

SET NODEFAULT COMMAND FILE 

When you save attributes, the default command 
file is TPU$COMMAND.TPU in your current 
directory or the command file that was executed 
at startup (see Section A. 3.4). Default setting. 

SET NODEFAULT SECTION FILE 

When you save attributes, EVE asks for the name 
of the section file you want to create (unless you 
disabled section file prompting). Default setting. 

SET NOEXIT ATTRIBUTE CHECK 

Disables attribute checking, typically to speed up 
or simplify exiting or quitting. Does not apply 
to the editing session in which you issue the 
command. Applies only to the editing sessions in 
which you use the section file or command file in 
which you saved the setting. 

SET NOSECTION FILE 

PROMPTING 

Disables prompting for a section file when you 
save attributes, typically to speed up or simplify 
saving attributes in a default section file or in a 
command file. 

SET SECTION FILE PROMPTING 

When you save attributes, EVE prompts you for 
the name of a section file. Default setting. 


You can save attributes during your editing session by using the SAVE 
ATTRIBUTES or SAVE EXTENDED EVE command or as part of exiting or 
quitting. By default, if you have changed attributes and not saved them, then on 
exiting EVE prompts you as follows: 
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Command: SET CURSOR BOUND 
Command: SET FIND CASE EXACT 
Command: SET TABS VISIBLE 


Command: EXIT 

Attributes were changed. Save them? [YES] 

If you want to save the changes, press the Return key. EVE then executes a 
SAVE ATTRI BUTES command before continuing the exit. If you do not want to 
save the changes, type No and press the Return key. EVE then continues exiting. 

To disable this prompting— typically, to make exiting faster or simpler— use the 
SET NOEXIT ATTRIBUTE CHECK command. However, the command does not 
apply to the current editing session because exit checking is itself a global setting 
that you can save in a section file or command file. After you save it, the setting 
applies to future editing sessions in which you use the relevant section file or 
command file. 

A.3.3 Saving Attributes in a Section File 

Typically, you save attributes in a section file. A section file is in binary form and 
saves attributes, key definitions (including learn sequences), menu definitions, 
compiled procedures, and other extensions to the editor— including any saved in 
the section file you are using. I n effect, the section file is your customized version 
of EVE. Because the section file is binary, it is executed quickly at startup. 

To create a section file, you can use the SAVE EXTENDED EVE command (as 
in previous versions of EVE) or the SAVE ATTRIBUTES command. When using 
SAVE EXTENDED EVE, you can specify the section file on the command line or 
let EVE prompt you for the section file name. When using SAVE ATTRIBUTES, 
you specify the section file as a response to a prompt. 

For example, the following command saves attributes and other customizations in 
a section file called MYSEC.TPU$SECTION in your current directory. 

Command: SAVE ATTRIBUTES 

Save attributes in a section file [YES]? Return 

File to save in: mysec 

DISK$1: [USER] MYSEC. TPU$SECTION; 1 created 

To speed up saving in a section file, you can set a default section file— that is, the 
section file you want to save in without having to specify the file each time you 
save attributes— and you can disable section file prompting. Table A-7 shows you 
the interaction of the settings for default section file and section file prompting. 


Table A-7 EVE Settings for Saving Attributes 

Commands Settings Effect with SAVE ATTRIBUTES 


SET DEFAULT SECTION FILE When you save attributes, EVE asks you 

SET SECTION FILE PROMPTING whether to save in a section file. Ifyou 

respond Yes (the default response), EVE 
saves in your default section file. If you 
respond No, EVE asks whether to save in a 
command file. 


(continued on next page) 
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Table A-7 (Cont.) EVE Settings for Saving Attributes 


Commands Settings 


Effect with SAVE ATTRIBUTES 


SET DEFAULT SECTION FILE 
SET NOSECTION FILE PROMPTING 


When you save attributes, EVE saves in 
your default section file without prompting. 


SET NODEFAULT SECTION FILE 
SET SECTION FILE PROMPTING 


When you save attributes, EVE asks 


whether to save in a section file. If you 
respond Yes, EVE asks for the name of a 
section file. If you respond No, EVE asks 


whether to save in a command file. Default 
settings. 


SET NODEFAULT SECTION FILE 
SET NOSECTION FILE PROMPTING 


When you save attributes, EVE asks 
whether to save in a command file (see 
Section A. 3.4). 


Typically, when you use SET DEFAULT SECTION FILE, you specify the section 
file you are going to use at startup for future editing sessions. The command does 
not determine the section file to be executed when you invoke the editor, but only 
the section file in which you save attributes and other customizations. 

Section files may be quite large, depending on the number of key definitions, 
menu definitions, and procedures you save. If you have limited disk space, 
you should save in a command file, which requires less disk space. For more 
information about creating and using section files, seethe EVE online help topic 
called Section Files. 


A.3.4 Saving Attributes in a Command File 


A command file contains DECTPU procedures and statements that are compiled 
and executed at startup. I n effect, this is a series of programs for extending EVE. 
(You can also use a command file for batch editing.) A command file may be 
slower at startup than a section file (depending on the number of procedures to 
be compiled and statements to be executed), but it takes up less disk space than a 
section file, and a command file can be edited and printed. Also, if you edit your 
command file, you can recompile procedures during your editing session by using 
EXTEND commands. The default file type for command files is .TPU. 

When you use the SAVE ATTRI BUTES command or when you save attributes on 
exiting or quitting, you can have EVE create or update a command file. EVE then 
generates a specially marked block of DECTPU statements for your settings and 
menu definitions. Thus, if you created a command file with procedures and key 
definitions of your own, you can have EVE append the block of attribute settings 
to this command file. Example A-l is a sample of the EVE -generated code. 
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Example A-1 EVE-Generated Code for Saving Attributes in a Command File 

! EVE-generated code begin 

! EVE attributes begin 

eve$set_find_case_sensitivity (FALSE) ; 

eve_set_box_noselect; 

eve_set_box_pad; 

eve_set_cursor_bound; 

eve_set_nodefault_command_file; 

eve_set_nodefault_section_file; 

eve_set_exit_attribute_check; 

eve_set_pending_delete; 

eve_set_nosection_file_prompting; 

eve_set_tabs ('INSERT'); 

eve_set_tabs ('VISIBLE'); 

! EVE attributes end 
! EVE-generated code end 

To save attributes in a command file, use the SAVE ATTRI BUTES command, as 
follows: 

Command: SAVE ATTRIBUTES 

Save attributes in a section file [YES]? no 

Save attributes in a command file [YES]? Return 

Enter file name [ TPU$ COMMAND . TPU] MYCOM 

14 lines written to file DISK$1: [USER] MYCOM. TPU; 1 

The prompt for the command file name shows, in brackets, the default command 
file that EVE uses if you press the Return key at the prompt without typing a file 
name. This default is one of the following: 

• The command file specified with the /COMMAND qualifier when you invoked 
EVE 

• A file called TPU$COMMAND.TPU in your current directory 

• The command file defined by the logical nameTPU$COMMAND 

You can set your preferred default command file— that is, the command file you 
want EVE to create or update without having to specify the file each time you 
save attributes. For example, the following command sets your default command 
file as MYCOM in your current directory: 

Command: SET DEFAULT COMMAND FILE MYCOM 

If you want to save in a command file rather than in a section file, you should 
also use the SET NOSECTI ON FILE PROM PTI NG command. Then, when you 
save attributes, EVE asks whether to save in a command file without first asking 
whether to save in a section file. 

Typically, when you use SET DEFAULT COMMAND FILE, you specify the 
command file you are going to use at startup for future editing sessions. 

The command does not determine the command file to be executed when you 
invoke EVE, but only the command file in which you save attributes and menu 
definitions. 

For more information about creating and using command files, see the EVE 
online help topic called Command Files. 
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A.3.5 Saving EVE Default Attributes 

The SAVE SYSTEM ATTRIBUTES saves EVE default settings and menu entries 
in a section file or command file. Thus, if you set several attributes and defined 
or undefined menu entries, you can use SAVE SYSTEM ATTRIBUTES to restore 
the standard EVE settings and menus to your section file or command file. 

SAVE SYSTEM ATTRI BUTES does not change the settings currently in effect— 
for example, it does not enable free cursor motion or invisible tabs— but saves 
only the EVE defaults in a section file or command file. 

A.4 Using DECTPU Within EVE 

You can use DECTPU within EVE to create DECTPU command files and to use 
the DECTPU debugging package. 

A.4.1 Creating DECTPU Command Files 

File creation switches and qualifiers determi ne whether DECTPU creates a buffer 
when it does not find the input file. The processing results of using this qualifier 
depend on the DECTPU application you are using. 

In EVE, files are created by default. If the input file does not exist, EVE uses the 
input file name and file type to create the buffer name. If you do not specify an 
input file, EVE creates a buffer named Main. 

To create DECTPU command files, use the /CREATE or/NOCREATE qualifiers, 
as follows: 

$ EDIT/TPU /CREATE (default) 

$ EDIT/TPU /NOCREATE 

Use the /NOCREATE qualifier to avoid invoking the editor in case you mistype 
the input file specification or to edit only an existing file. 

If EVE does not find an input file you have specified, it terminates the editing 
session and returns you to the system level, as in the following example: 

$ EDIT/TPU NEW. DAT /NOCREATE 
Input file does not exist: NEW. DAT; 

A.4.2 Using a DECTPU Debugging Package 

Debug switches and qualifiers determine whether DECTPU runs a debug file. A 
debug file is useful for testing procedures for an application that you are creating. 

To start editing the code in the file you are debugging, follow these steps: 

1. Use the GO command. You cannot use wildcards to specify the debug file. 

2. Specify only one debug file at a time. DECTPU compiles and executes the 
debug file before executing TPU$INIT_PROCEDURE. 

The debugger that is supplied with DECTPU is in 

SYS$SHARE:TPU$DEBUG.TPU. This file provides commands to manipulate 
variables and to control program execution. 

There are two ways to specify a debug file of your own: 

• Define the logical nameTPU$DEBUG to specify your debugger file, and then 
use the /DEBUG qualifier when you invoke DECTPU. You can enter the 
definition in your LOGIN.COM file. 
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• U se the /DEBUG = qualifier and specify a debugger file. 

This overrides any definition of theTPU$DEBUG logical name. The default 
file type is .TPU. For example, the following command uses a debugger file 
named MYDEBUG.TPU to edit a file named MYPROCS.TPU: 

S EDIT/TPU MYPROCS.TPU /DEBUG=MYDEBUG 

DECTPU assumes the debugger file is in SYS$SHARE. If your debugger file 
is stored elsewhere, use a complete file specification, including the device 
(disk) and directory. 

For more information about the DECTPU debugging package, read the comments 
in the source file or see the DEC Text Processing Utility Reference Manual. 

A.5 Using DECTPU Procedures to Extend EVE 

The EVE editor is built on the DEC Text Processing Utility (DECTPU). With 
the EVE command TPU, you can enter any DECTPU statement or series of 
statements that can be expressed on one command line. 

To enter a DECTPU command, enter the command TPU followed by the DECTPU 
statement you want to execute. For example, to execute the DECTPU statement 
APPENDJJ NE, which places the current line at the end of the previous line, 
enter the following command string: 

Command: TPU APPEND_LINE 

For more information about theTPU command, type FIELP TPU. Seethe 
DEC Text Processing Utility Reference Manual for a complete list of DECTPU 
statements and procedures. 

A.5.1 Writing DECTPU Procedures 

Because EVE is an editor written in the DECTPU programming language, you 
can extend EVE functions by writing procedures in DECTPU. This section 
assumes that you are familiar with the DECTPU programming language 
described in theDEC Text Processing Utility Reference Manual. 

Before you begin writing DECTPU procedures to modify EVE, Digital 
recommends that you study the EVE source code, which is stored in 
SYS$EXAMPLE:EVE$*.TPU. (The wildcard character in the file specification 
indicates that EVE source code is stored in many files.) These files are put 
together by using EVE$BUILD. Variables and statements in your procedures 
should be consistent with EVE variables and statements so that you can avoid 
making changes that adversely affect EVE operations. 

You can write procedures in the DECTPU programming language that are, in 
effect, new EVE commands. When you write new EVE command procedures, 
follow these rules: 

• Prefix the procedure name with the label EVE_ so that EVE recognizes the 
procedure as an EVE command. After you compile the procedure, execute 
it by pressing the Do key and typing the procedure name without the EVE_ 
prefix or the underscores. For example, enter SET LEFT MARGIN for the 
EVE_SET_LEFT_M ARGI N procedure. (You can also define a key to execute 
the new command.) 
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• The words PROCEDURE and ENDPROCEDU RE must start in column 1. 

• I nitialize all global variables in a single procedure named TPU$LOCAL_l NIT 
or in a module initialization procedure if you build with EVE$BUI LD. 

If the EVE command you are writing takes any integer parameters, such as SET 
LEFT MARGIN 2, where 2 is the parameter, you must define a global variable 
to associate that parameter with the data-type integer. When you are using the 
EVE commands that you have defined, EVE passes the null string (" ") if you do 
not provide a value for a string parameter; it passes the value EVE$K_NO_ARG 
if you do not provide a value for an integer parameter. 

Digital recommends placing global variables in a procedure called TPU$LOCAL_ 

I NIT, which is called each time EVE starts. Place all procedures that use 
parameters in the same file that contains theTPU$LOCAL_INIT procedure. The 
following is an example of a global variable definition for command parameters: 

• The following definition of the global variable EVE$ARG1_ADD tells EVE to 
expect an integer as the first parameter for EVE_ADD: 

EVE$ARG1_ADD := "INTEGER"; 

• The following definition of the global variable EVE$ARG1_H ELLO tells EVE 
to expect a string as the first parameter to EVE_H ELLO: 

EVE$ARG1_HELL0 ;= "STRING"; 

The integer variables are required. 

In general, each of the global variable names that define command parameters 
must consist of the following three parts: 

• The first part of the variable name must be &/e$. 

• The second part defines the variable's sequence within a procedure. For the 
first variable, it is argl\ for the second, arg2\ and so on. 

• The third part of the variable name is the procedure name without the EVE_ 
prefix. 

A.5.2 Compiling DECTPU Procedures 

The EXTEND EVE command enables you to compile a DECTPU procedure 
without leaving EVE. To compile the procedure that the cursor is in, use the 
EXTEND THIS command. To compile one procedure, enter the command 
EXTEND EVE and the name of the procedure you want to compile. To compile 
all proceduresin a file, enter the command EXTEND EVE * (which is the same as 
the EVE command EXTEND ALL). If you miss a message from the compiler, use 
the command BUFFER MESSAGES to read the messages stored in the Messages 
buffer. 
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The following example illustrates how to create and compile DECTPU procedures 
to define an ADD command, a HELLO command, and the parameters for both 
commands. Invoke EVE to edit the file MYPROCEDURES.TPU and insert the 
following text into the file: 

! Procedure to add two integers and display the result in the message window 

PROCEDURE EVE_ADD (Al, A2) 

LOCAL TEMP, 

Nl, 

N2; 

IF NOT EVE $PR0MP T_NUMBER (Al, Nl, "First number to add: ", 

"No number specified.") 

THEN 

RETURN (FALSE) ; 

ENDIF; 

IF NOT EVE $PR0MP T_NUMBER (A2, N2, "Second number to add: ", 

"No number specified.") 

THEN 

RETURN (FALSE) ; 

ENDIF; 

TEMP := Nl + N2 ; 

MESSAGE (STR (Nl) + " + " + STR (N2) + " = " + STR (TEMP)); 

RETURN (TRUE) ; 

ENDPROCEDURE; 

PROCEDURE EVE_HELLO (MY_NAME) 

LOCAL THE_NAME; 

IF EVE$PROMPT_STRING (MY_NAME, THE_NAME, "Name: ", "We haven't met") 

THEN 

MESSAGE ("Hello " + THE_NAME) ; 

RETURN (TRUE) ; 

ELSE 

RETURN (FALSE) ; 

ENDIF; 

ENDPROCEDURE; 

EVE$ARG1_ADD := "INTEGER"; 

EVE$ARG2_ADD := "INTEGER"; 


Use the syntax shown in the file MYPROCEDURES.TPU to put the definitions 
for the two parameter variables in your TPU$LOCAL_l NIT procedure. 

To compile the procedures you have entered into MYPROCEDURES.TPU, press 
the Do key, type EXTEND EVE *, and press the Return key. If you are going 
to use the newly compiled commands in the current editing session, you must 
execute TP U$LOCAL_l NIT by entering the command TPU TPU$LOCAL_INIT. 

A.6 Creating Section Files 

A section file contains key definitions, learn sequences, and compiled DECTPU 
statements and procedures in binary form. Because section files are in binary 
form, they set up the editing environment very quickly, but you cannot display 
or edit a binary file. Use a section file to implement editing features that are 
not likely to change from one editing session to another. The default file type for 
section files is ,TPU$SECTION. 
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EVE requires a section file for startup. By default, EVE uses the section file 
EVE$SECTI ON ,TPU$SECTI ON located in directory SYS$SHARE. This default 
section file defines the editing keys, shown in Figure 8-2 and Figure 8-3, as well 
as the standard EVE commands. 

Rather than use the default section file, you can create a modified section file that 
contains the standard EVE functions as well as your own key definitions, learn 
sequences, and editing functions. You can create a section file in two ways: 

• If you have a small number of key definitions and learn sequences, define 
editing keys and assign learn sequences interactively. To save the definitions 
in a section file, enter the SAVE EXTENDED EVE command. 

The default file type for section files is ,TPU$SECTION. Each time you enter 
the SAVE EXTENDED EVE command, you can specify the same file to ensure 
that all your customizations are saved cumulatively in the same file. 

• If you have a large number of modifications, create a command file with 
key definitions and DECTPU procedures. (Note, however, that a command 
file cannot have learn sequences.) End the file with the SAVE and QUIT 
statements, assigning a section file name with the file type ,TPU$SECTION, 
as shown in Example A-2. Then invoke EVE with the /COMMAND qualifier 
and the command file name. EVE executes statements in the command file, 
saves the compiled procedures and key definitions in the section file named 
in the SAVE statement, and then executes the QUIT statement, returning 
control to the DCL. You can now use the new section file, as named in the 
SAVE statement. 

To use a section file, specify the section file name with the /SECTION qualifier on 
the EVE command line. For example, the following command invokes EVE with 
a section file named MY_SECTION.TPU$SECTION, located in directory ALEXIS 
on a disk called WORK1: 

$ EDIT/TPU/SECTI0N=W0RK1 : [ALEXIS] MY_SECTION 

By default, DECTPU uses the section file whose logical name isTPU$SECTION. 
If you define this logical name in your LOGIN.COM file, DECTPU automatically 
uses your section file when you invoke EVE. For example: 

S DEFINE TPDSSECTION W0RK1 : [ALEXIS]MY_SECTION . TPDSSECTION 

Use the EVE command SHOW SUMMARY to display the name of the current 
section file. 

EVE executes a section file before a command file or an initialization file. 
Therefore, definitions in the command file and initialization file override 
section file definitions. When you want to set the characteristics of the editing 
environment, use either a command file or an initialization file. EVE executes 
these commands upon startup, so the appearance of the buffer and the editing 
mode is adjusted according to your definition. 

A.7 Creating Command Files 

A command file is a source program that contains DECTPU procedures and 
executable statements. A DECTPU procedure is a set of related DECTPU 
statements that are executed when the procedure name is invoked. The 
statements and procedures define what happens when you press a key or enter a 
command. The default file type for command files is ,TPU. 


A-21 


Customizing EVE 

A.7 Creating Command Files 

When you use an EVE command, you are actually invoking a compiled DECTPU 
procedure. For example, the EVE command SET KEYPAD EDT invokes the 
EVE_SET_KEYPAD_EDT procedure in the standard EVE section file. 

EVE executes a command file after a section file. For this reason, any key 
definitions or procedures defined in a command file override those in a section 
file. 

There are two different ways to use a command file. A command file can create 
an editing environment that is independent of the section file, or a command file 
can be used to produce a new section file. 

Whenever you want to set editing defaults, use a command file because EVE 
executes the statements in the command file (or initialization file) at startup 
and applies the new defaults. See Section A. 8 for a list of commands that set 
the editing environment. For example, you can use one command file to set up 
margins and tabs and a header for a memo, and another command file that sets 
tabs suitable for writing a financial report. 

To create a command file, invoke EVE and specify a file name with a file 
type .TPU, such as MY_COMMAND.TPU. Once in the editor, enter DECTPU 
statements and procedures. 

Example A-2 shows a command file that modifies EVE to be more like 
the EDT editor. This file creates a personal section file named MY_ 

SECTI ON .TPU $SECTI ON . 

If you intend to use a command file to create a section file, conclude the file with 
the SAVE and QUIT statements and include a file specification for the section 
file, as described in Example A-2. To convert the command file to a section file, 
invoke EVE with the /COMMAND qualifier. For example: 

$ EDIT/ TPU/COMMAND=MY_COMMAND S 

EVE executes the commands in the file and saves the compiled procedures and 
key definitions in the TPU $SECTI ON file that you name in the SAVE statement. 
The QUIT statement terminates the editor, returning control to the DCL prompt. 
At this point, you have a new section file. Therefore, on invoking EVE, the editor 
automatically reads the section file that you have defined in your LOGIN.COM or 
in your SYSLOGIN directory. 

One advantage of creating a section file from a command file is that a command 
file can be easily edited. This is especially important when you want to add 
DECTPU procedures or add a large number of key definitions. 

To use a command file to set the characteristics of the editing environment 
and add functions to the standard EVE editor, again invoke EVE with the 
/COMMAND qualifier. For example: 

$ EDIT/ TPU/ COMMAND=DATA_SETUP 

EVE again executes the statements in the command file but because there is no 
SAVE statement, the compiled procedures and key definitions are not saved. 

If you do not include a command qualifier, EVE searches for the file specified 
by the logical name TPU $COM MAN D. You can define this logical name in your 
LOGIN.COM file. If this file is not found, DECTPU then searches for a file 
named TPU$COMMAND.TPU in the current directory. 
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Example A-2 Sample EVE Command File 


I****************************************************************************** 

! Command file making EVE more like EDT and implementing personal customizations 

I ****************************************************************************** 

! Procedure to delete a line and close the gap left by the deletion 1 


PROCEDURE EVE_ZAPLINE 2 
EVE_END_OF_LINE ; 3 
EVE_ERASE_START_OF_LINE ; 4 
EVE_DELETE; 

ENDPROCEDURE 5 


! Procedure to move the cursor to the beginning of the next paragraph: 

PROCEDURE EVE_NEXT_PARAGRAPH 6 

LOCAL PAT1 , 

THE_RANGE; 

PAT1 := linejoegin + line_begin + ARB (1); 

THE_RANGE := SEARCH_QUIETLY (PAT1, forward, exact); 

IF THE_RANGE <> 0 
THEN 

POSITION (ENDJDF (THE_RANGE) ) ; 

RETURN (TRUE) ; 7 

ELSE 

RETURN (FALSE) ; 

ENDIF; 

ENDPROCEDURE 

(Procedure to make EVE behave more like EDT 
PROCEDURE EVE_MIMIC_EDT 

EVE_SET_KEYPAD_EDT ; 

EVE_SET_CURSOR_BOUND ; 

EVE_SET_LEFT_MARGIN (10) ; 8 

ENDPROCEDURE 

(Procedure to transpose two characters 
PROCEDURE EVE_TRANSPOSE 
LOCAL WHACK; 

WHACK := ERASE_CHARACTER (1) ; 

MOVE_HORIZONTAL (1); 

COPY_TEXT (WHACK) ; 

RETURN (TRUE) ; 

ENDPROCEDURE 


(continued on next page) 
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Example A-2 (Cont.) Sample EVE Command File 

! Procedure to make both the screen width and the right margin narrow 

PROCEDURE EVE_NARROW_SCREEN 

EVE_SET_WIDTH (80); 

EVE_SET_RIGHT_MARGIN (79); 

ENDPROCEDURE; 

! Procedure to make both the screen width and the right margin wide 

PROCEDURE EVE_WIDE_SCREEN 

EVE_SET_WIDTH (132); 

EVE_SET_RIGHT_MARGIN (131); 

ENDPROCEDURE; 

! Procedure to toggle screen width and right margin from the current setting 
!to the other setting, i.e. change to wide if narrow, change to narrow if wide 

PROCEDURE E VE_C HAN GE_W I D T H 9 

IF GET_INFO (SCREEN, "width") <> 80 

THEN 

E VE_NARROW_S CRE E N ; 

ELSE 

EVE_WIDE_SCREEN; 

END IF; 

ENDPROCEDURE; 

PROCEDURE TPU$LOCAL_INIT 10 

EVE_MIMIC_EDT; 11 

EVE$DEFINE_KEY ( " EVE_NEXT_PARAGRAPH " , CTRL_P_KEY, "Next Para", 

EVE$X_USER_KEYS) ; 12 

EVE$DEFINE_KEY ( "EVE_ZAPLINE" , KEY_NAME ("0", SHIFT_KEY) , "Zap Line", 
EVE$X_USER_KEYS) ; 13 

EVE $ DEF I NE_KE Y ( "EVE_TW0_WIND0WS" , F17, "Two Windows", EVE$X_USER_KEYS) ; 14 

EVE$DEFINE_KEY ( "EVE_OTHER_WINDOW" , CTRL_G_KEY, "Other Window", 
EVE$X_USER_KEYS) ; 15 

EVE$DEFINE_KEY ( "EVE_GET_FILE ('')", KEY_NAME (KP6, SHIFT_KEY) , "Get File", 
EVE$X_USER_KEYS) ; 16 

EVE$DEFINE_KEY ( "EVE_TRANSPOSE " , KEY_NAME (F20, SHIFT_KEY) , "Transpose", 
EVE$X_USER_KEYS) ; 17 

ENDPROCEDURE 

TPU$LOCAL_INIT; 18 

SAVE ("WORK: [LINCOLN]MY_SECTION.TPU$SECTION") ; 19 

QUIT; 20 

Example A-2 illustrates the following points about writing command files: 

1 Use comments to document a command file. An exclamation point starts 
a comment. When DECTPU encounters the exclamation point, it ignores 
everything else on the line. 

2 Start each procedure with the word "procedure". 

3 End each DECTPU statement in the procedure with a semicolon. 
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4 Each EVE command corresponds to the name of a DECTPU procedure in the 
section file of standard EVE (SYS$SHARE:EVE$SECTION.TPU$SECTION). 

You can use the names of these DECTPU procedures in procedures you write, 
or you can execute them independently as DECTPU statements. If your 
command file contains both user-written procedures and executable DECTPU 
statements, put all the procedures before any of the executable statements. 

5 End each procedure with the word "endprocedure". 

6 When you write a procedure that implements a command in EVE, use 
EVE_ as the first four characters of the procedure name. By following this 
convention, the procedure name, without the characters EVE_, becomes an 
EVE command. For example, if you write a procedure called EVE_NEXT_ 
PARAGRAPH in a command file, once the section file is compiled, you can use 
the new EVE command NEXT PARAGRAPH. 

Because a command file executes after a section file, a procedure overwrites a 
command by the same name in the section file. For example, if you name a 
procedure EVE_ERASE_CH ARACTER, the ERASE CHARACTER command 
executes your procedure, not the standard EVE command. 

7 For an EVE command to be usable with a repeat count (either by itself or as 
part of a learn sequence), it must return TRUE when it succeeds. 

8 If you use a DECTPU procedure name that requires a parameter, put the 
parameter in parentheses. For example, the EVE command SET LEFT 
MARGI N requires a parameter specifying where to set the left margin. The 
EVE syntax is as follows: 

SET LEFT MARGIN 10 

The DECTPU syntax is as follows: 

eve_set_left_margin(1 0); 

If a parameter is a string rather than an integer, enclose the parameter in 
quotation marks (" ") For example, with EVE_SET_SCROLL_MARGI NS, the 
parameter "10%" is a string and must be enclosed in quotation marks. To 
pass a null parameter, use an empty pair of quotation marks (" ") such as 
eve_spawn( " "). 

9 A procedure must be compiled before it can be invoked. Then the procedure 
can be invoked as either an EVE command or as a DECTPU executable 
statement. In this example, the procedure named EVE_CH ANGE_WI DTH 
can be invoked as the EVE command CHANGE WIDTH. The procedure name 
can also be invoked as the DECTPU executable statement EVE_CHANGE_ 
WIDTH. 

10 Add a procedure called TPU$LOCAL_l NIT to a command file that you use as 
a section file. 

This procedure should contain all executable statements (including those 
calling other procedures) that you want to be defined and executed when EVE 
is invoked. Because any executable statement in this procedure is executed 
when EVE is invoked, the statements in this procedure become default 
settings for the EVE editor. 
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11 This DECTPU statement invokes the procedure EVE_MIMIC_EDT, which 
contains DECTPU statements that change EVE's settings. If you compile the 
sample command file, save it in a personal section file, and use that section 
file to invoke EVE. By doing this, the keypad setting, cursor style, and left 
margin are automatically set by the procedure EVE_MI MIC_EDT. As a result, 
EVE behaves like EDT at startup. 

12 This DECTPU statement uses the predefined EVE routine EVE$DEFI NE_ 
KEY to define the user-written procedure EVE_NEXT_PARAGRAPH for 
the key sequence Ctrl/P. The EVE$DEFI NE_KEY routine ensures that 
the program bound to the key has an error handler. The DECTPU built-in 
DEFINE_KEY does not perform this step. 

There are four parameters to EVE$DEFI NE_KEY. (This routine uses the 
same parameters as the DECTPU built-in DEFINE_KEY.) The first specifies 
the EVE procedure or command to be bound to a key. The second specifies the 
key to which the command should be bound. The third specifies the label that 
EVE should use for the key in the H el p keypad diagram. The fourth is an 
EVE variable specifying the keymap list in which the key definition should be 
saved. Use the variable name EVE$X_USER_KEYS for the fourth parameter 
unless you are an advanced user implementing a special application. 

13 This DECTPU statement defines the procedure EVE_ZAPLINE for the key 
sequence GOLD 0. This line demonstrates the DECTPU syntax to use when 
defining a sequence that consists of of the GOLD key plus a letter key. Using 
"shift_key" makes the definition case insensitive, so that both o and O are 
defined. 

14 This statement defines the EVE command TWO Wl NDOWS for the F17 key. 

15 This statement defines the EVE command OTHER WINDOW for the key 
sequence Ctrl/G. 

16 This statement defines the EVE command GET FILE for the key sequence 
GOLD KP6. This keypad binding supersedes the previous definition of the 
GOLD KP6 key. The EVE_M I M I C_EDT procedure sets the keypad to EDT 
and the EDT keypad then binds the GOLD KP6 key sequence to the INSERT 
HERE command. However, this DECTPU statement changes the key binding 
to the GET FILE command. The pair of single quotes passes a null argument 
to the procedure. 

17 This statement defines the procedure EVE_TRANSPOSE for the key sequence 
GOLD F20. 

is The statement TPU$LOCAL_l NIT calls the procedure TPU$LOCAL_l NIT, 
which is then executed, creating new default settings for EVE. 

19 Enter the SAVE statement to create a new section file. I n parentheses and 
quotation marks, specify the device, directory, and file name of the section 
file. To update a section file, specify the existing personal section file. 

20 Add the statement QUIT as the last statement in a command file if the file 
is to be compiled as a section file. QUIT ends EVE processing and returns 
control to the DCL prompt. 
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A.8 Creating Initialization Files 

Rather than defining keys or setting the characteristics of an editing session 
interactively, you can put EVE commands and key definitions in an initialization 
file. You can execute an initialization file when invoking EVE or during an 
editing session by using the execute procedure ( @) command. For example, 

Command: @SETUP_INIT 

Each command in an initialization file begins on a separate line. You can add 
comments to the file to document it, as long as you precede the comments with 
an exclamation point and place them on a line separate from a command. An 
initialization file has a filetype .EVE. 

The following is an example of an initialization file: 

SET TABS EVERY 5 
SET LEFT MARGIN 15 
SET RIGHT MARGIN 75 
OVERSTRIKE MODE 
DEFINE KEY=Ctrl/D ERASE WORD 
DEFINE KEY=G0LD W START OF LINE 
DEFINE KEY=KP5 FILL PARAGRAPH 
| 

! Binds the EDT forward function (KP4 on 
!EDT keypad) to GOLD F 
| 

DEFINE KEY=G0LD F EDT KP4 

You can specify an initialization file with the /I NITI ALIZATI ON qualifier, 
defined as EVE$INIT in your LOGIN.COM file or named EVE$INIT.EVE in 
your SYS$LOGIN directory. The following command invokes EVE with the 
initialization file named MY_I NIT: 

S EDIT/TPU/INIT=W0RK1 : [ALEXIS] MY_INIT 

By default, DECTPU uses the initialization file whose logical name is EVE$I NIT. 
If you define this logical name in your LOGIN.COM file, DECTPU automatically 
uses your initialization file when you invoke EVE. For example, you could insert 
the following command in your LOGIN.COM file: 

$ DEFINE EVESINIT W0RK1 : [ALEXIS] MY_INIT. EVE 

When EVE starts up, it looks first for a section file, then for a command file, and 
finally for an initialization file. Because an initialization file is executed after a 
section file and a command file, the definitions in an initialization file override 
those in a section file or a command file. For this reason, place commands that 
define the editing environment in either your command file or your initialization 
file. Commands that define the environment include the following: 

• SET CURSOR BOUND or FREE 

• SET FIND WHITESPACE or NOWHITESPACE 

• SET GOLD KEY 

• SET KEYPAD 

• SET LEFT MARGIN 

• SET RIGHT MARGIN 

• SET SCROLL MARGINS 

• SET TABS AT or EVERY 
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• SET TABS SPACES, MOVEMENT, or INSERT 

• SET TABS VISIBLE or INVISIBLE 

• SET WIDTH 

• SET WILDCARD VMS or ULTRIX 

• SET WRAP or NOWRAP 

• The default mode of the buffer: CHANGE MODE, OVERSTRI KE MODE, or 
INSERT MODE 

• The default direction of the buffer: CHANGE Dl RECTI ON, FORWARD, or 
REVERSE 

A.9 Saving Your Customizations in Startup Files 

You can save key definitions, learn sequences, or DECTPU procedures in a 
startup file. With a startup file, you can save all the modifications you have made 
to EVE so you do not have to recreate your modifications at each editing session. 

EVE has three types of startup files: 

• Section files 

• Command files 

• I nitialization files 

You can customize section files and command files interactively from the EVE 
editor. You create initialization files separately. 

When saving your customizations in a section file or command file, use the SAVE 
ATTRIBUTES command or the SAVE EXTENDED EVE command when you exit 
from or quit the editor. 

Table A-8 summarizes the commands for saving attributes. 


Table A-8 EVE Commands for Saving Attributes 

Command Usage or Effect 

SAVE ATTRIBUTES Saves attribute settings and user menu definitions in a 

section file or command file, depending on your responses 
to EVE prompts or on settings done with other EVE 
commands. If you save in a section file, the effect is 
the same as SAVE EXTENDED EVE. If you save in a 
command file, EVE generates a specially marked block 
of DECTPU statements for attribute settings and menu 
definitions and either creates a command file or updates 
an existing command file with this block of statements. 

SAVE SYSTEM ATTRIBUTES Saves EVE default attribute settings in a section file or 

command file. This is useful if you want to restore your 
section file or command file to the standard EVE settings 
and menu definitions. 


(continued on next page) 
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Table A-8 (Cont.) EVE Commands for Saving Attributes 

Command Usage or Effect 


SAVE EXTENDED EVE 


SET DEFAULT COMMAND FILE 

SET DEFAULT SECTION FILE 
SET EXIT ATTRIBUTE CHECK 
SET NODEFAULT COMMAND FILE 

SET NODEFAULT SECTION FILE 

SET NOEXIT ATTRIBUTE CHECK 

SET NOSECTION FILE PROMPTING 

SET SECTION FILE PROMPTING 


Creates a section file, saving attribute settings, key 
definitions, menu definitions, compiled procedures, and 
other extensions, such as global variables set with a 
DECTPU statement. If you do not specify a section file on 
the command line, EVE prompts you for one or uses your 
default section file (if you set a default). 

Determines the command file for saving attributes. Does 
not determine the command file to be executed at startup, 
if any. 

Determines the section file for saving attributes. Does not 
determine the section file to be executed at startup. 

If you changed attributes, then when you exit or quit, EVE 
asks if you want to save your changes. Default setting. 

When you save attributes, the default command file is 
TPU$COM MAN D.TPU in your current directory or the 
command file that was executed at startup. Default 
setting. 

When you save attributes, EVE asks for the name of the 
section file you want to create (unless you disabled section 
file prompting). Default setting. 

Disables attribute checking, typically to speed up or 
simplify exiting or quitting. Does not apply to the editing 
session in which you issue the command, but only to the 
editing sessions in which you use the saved section file or 
command file. 

Disables prompting for a section file when you save 
attributes, typically to speed up or simplify saving 
attributes in a default section file or in a command file. 

When you save attributes, EVE prompts you for the name 
of a section file. Default setting. 


If you have changed attributes and not saved them, when exiting from EVE, you 
are asked if you want to save the changed attributes. For example: 

Command: SET CURSOR BOUND 
Command: MOVINGJTEXT 
Command: SET TABS VISIBLE 


Command: EXIT 

Attributes were changed. Save them? [YES] 

If you want to save the changes, press the Return key. EVE then does a SAVE 
ATTRI BUTES command before exiting. If you do not want to save the changes, 
type No and press Return. EVE then continues exiting. 

To disable this prompting, for a faster or simpler exit, use the SET NOEXIT 
ATTRIBUTE CHECK command. However, the command does not apply to the 
current editing session because exit checking is itself a global setting and can be 
saved in a section file or command file. After you save it, the setting applies to 
future editing sessions in which you use the relevant section file or command file. 


A-29 


Customizing EVE 

A.9 Saving Your Customizations in Startup Files 

Other global attributes (such as scroll margins or the types of wildcards) and any 
buffer-specific attributes (such as margins or tab stops) are not saved in a section 
file or a command file. Typically, you use an initialization file for those settings. 

There are several ways in which you can use all your customizations in future 
editing sessions. You can combine different types of startup files in the following 
ways: 

• Section file and an initialization file 

• Command file (EVE -generated code) and an initialization file 

If you have limited disk space, use a command file instead of a section file. 

• Command file (EVE-generated and user-generated code) 

You can write DECTPU procedures for attributes that typically are contained 
in an initialization file and use them in a command file containing EVE- 
generated code. Command files execute more quickly than an initialization 
file and offer more sophisticated editing tools. 

Table A-9 lists the categories of commands for EVE attributes and features and 
shows in what type of startup file you can save them. 


Table A-9 EVE Startup Files 

Attribute/Feature 

Section 

Command Initialization 

Key Definitions 

DEFINE KEY 

X 

X 

X 

LEARN 

X 

- 

- 

SET FUNC KEYS [NOJDECWI N DOWS 

X 

X 

X 

SET [NOJGOLD KEY 

X 

X 

X 

SET KEYPAD [NO]EDT 

X 

X 

X 

SET KEYPAD [NO]WPS 

X 

X 

X 

SET KEYPAD VT100 

X 

X 

X 

SET KEYPAD NUMERIC 

X 

X 

X 

UNDEFINE KEY 

X 

X 

X 




(continued on next page) 
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Table A-9 (Cont.) EVE Startup Files 


Attribute/Feature 

Section 

Command 

Initialization 

Global Settings-1 

SET BOX [NO]PAD 

X 

X 

X 

SET BOX [NO]SELECT 

X 

X 

X 

SET CURSOR FREE or BOUND 

X 

X 

X 

SET [NO]CLI PBOARD 

X 

X 

X 

SET [NO]DEFAULT COMMAND FILE 

X 

X 

X 

SET [NO]DEFAULT SECTION FILE 

X 

X 

X 

SET [NO]EXIT ATTRIBUTE CHECK 

X 

X 

X 

SET FIND CASE [NO]EXACT 

X 

X 

X 

SET [NO]PENDING DELETE 

X 

X 

X 

SET [NO]SECTION FILE PROMPTING 

X 

X 

X 

SET TABS INSERT, MOVEMENT, or SPACES 

X 

X 

X 

SET TABS [INVISIBLE 

X 

X 

X 

Global Settings-2 

SET FIND [NO]WH ITE SPACE 

- 

- 

X 

SET SCROLL MARGINS 

- 

- 

X 

SET WIDTH 

- 

- 

X 

SET WILDCARDS VMS or ULTRIX 

- 

- 

X 

Buffer Settings 

FORWARD or REVERSE 

- 

- 

X 

INSERT MODE or OVERSTRIKE MODE 

- 

- 

X 

SET BUFFER 

- 

- 

X 

SET [NOD OURNALING ALL 

- 

- 

X 

SET LEFT MARGIN 

- 

- 

X 

SET PARAGRAPH INDENT 

- 

- 

X 

SET RIGHT MARGIN 

- 

- 

X 

SET TABS AT or EVERY 

- 

- 

X 

SET [NOJWRAP 

- 

- 

X 

DECTPU Procedures 


X 

X 

- 


By placing your definitions and procedures in a startup file, you can invoke the 
editor and automatically establish the editing environment your task requires. 
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A.9.1 Saving in a Section File 

To save a section file, use the SAVE EXTENDED EVE command or the SAVE 
ATTRIBUTES command. Using SAVE EXTENDED EVE, you can specify the 
section file on the command line or let EVE prompt you for the section file name. 
Using SAVE ATTRI BUTES, you specify the section file as a response to a prompt. 


For example, the following command saves attributes and other customized 
settings in a section file called MYSEC.TPU$SECTION in your current directory: 

Command: SAVE ATTRIBUTES 

Save attributes in a section file [YES]? | Return | 

File to save in: mysec 

DISK$1: [USER] MYSEC. TPU$SECTION; 1 created 

To speed up saving in a section file, you can set a default section file— that is, the 
section file you want to save in without having to specify the file each time you 
save attributes— and you can disable section file prompting. Table A- 10 shows 
the interaction of the settings for default section file and section file prompting. 


Table A-10 EVE Settings for Saving Attributes 

Command Settings Effect with SAVE ATTRIBUTES 


SET DEFAULT SECTION FILE 
SET SECTION FILE PROMPTING 


SET DEFAULT SECTION FILE 
SET NOSECTION FILE PROMPTING 

SET NODEFAULT SECTION FILE 
SET SECTION FILE PROMPTING 


SET NODEFAULT SECTION FILE 
SET NOSECTION FILE PROMPTING 


When you save attributes, EVE ask you whether to save 
in a section file. If you respond Yes (the default response), 
EVE saves in your default section file. If you respond No, 
EVE asks whether to save in a command file. 

When you save attributes, EVE saves in your default section 
file without prompting. 

Default settings. When you save attributes, EVE asks 
whether to save in a section file. If you respond Yes, EVE 
asks for the name of a section file. If you respond No, EVE 
asks whether to save in a command file. 

When you save attributes, EVE asks whether to save in a 
command file. 


Typically, when you use SET DEFAULT SECTION FILE, you specify the section 
file you are going to use at startup for future editing sessions. The command does 
not determine the section file to be executed when you invoke the editor, but only 
the section file in which you save attributes and other customized settings. To 
specify the section file you want executed at startup, do either of the following: 

• Use EDIT/TPU/SECTI ON and specify the section file you want to use: 

$ EDIT/TPU/SECTION=MYEVE 

• Define the logical nameTPU$SECTION to specify the section file, and then 
use the EDIT/TPU command: 

$ DEFINE TPU$SECTI0N SYS$LOGIN:MYEVE 
$ EDIT/TPU 

In specifying the section file to be executed, you must use a complete file 
specification, including the device (or disk) and directory; otherwise, DECTPU 
assumes the section file is in SYS$SHARE. 
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Section files may be quite large, depending on the number of customized settings 
you save. If you have limited disk space, you should save in a command file, 
which requires less disk space. For more information about creating and using 
section files, seethe EVE online help topic called Section Files. 

A.9.2 Saving in a Command File 

When you use the SAVE ATTRI BUTES command or when you save attributes on 
exiting or quitting, you can have EVE create or update a command file. To save 
attributes in a command file, use the SAVE ATTRI BUTES command, as follows: 

Command: SAVE ATTRIBUTES 

Save attributes in a section file [YES]? no 

Save attributes in a command file [YES]? | Return | 

Enter file name [TPU$COMMAND . TPU] MYCOM 
14 written to file DISK$1 : [USER] MYCOM. TPU; 1 

The prompt for the command file name shows, in brackets, the default command 
file that EVE uses if you press the Return key at the prompt without typing a file 
name. This default is one of the following: 

• The command file specified with the /COMMAND qualifier when you invoked 
EVE 

• The command file defined by the logical name TPU $COM MAN D 

• A command file called TPU $COM MAN D.TPU in your current directory 

You can set your preferred default command file— that is, the command file you 
want EVE to create or update, without having to specify the file each time you 
save attributes. For example, the following command sets your default command 
file as MYCOM .TPU in your current directory: 

Command: SET DEFAULT COMMAND FILE MYCOM 

If you want to save in a command file rather than in a section file, you should 
also use the SET NOSECTION FILE P ROM PTI NG command. Then, when you 
save attributes, EVE asks whether to save in a command file without first asking 
whether to save in a section file. 

When you use SET DEFAULT COMMAND FILE, you usually specify the 
command file you are going to use at startup for future editing sessions. 

The command does not determine the command file to be executed when you 
invoke EVE, but only the command file in which you save attributes and menu 
definitions. To specify the command file you want executed at startup, do any of 
the following: 

• Use EDIT/TPU/COMMAND and specify the command file you want to use: 

$ EDIT/ TPU/ COMMAND=MYEVE 

• Define the logical name TPU $COM MAN D to specify the command file, and 
then invoke EVE using EDIT/TPU : 

$ DEFINE TPU$ COMMAND SYS$LOGIN:MYEVE 
$ EDIT/TPU 

• Name the command fileTPU$COMMAND.TPU in your current directory, and 
then use EDIT/TPU to invoke EVE. 

For more information about creating and using command files, see the EVE 
online help topic called Command Files. 
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A.10 Converting from EDT to EVE 

If you are accustomed to the EDT editor, you can customize EVE to work in 
similar ways by using a section file, an initialization file, or both, or by using 
DECTPU procedures. 

Typically, you save key definitions, learn sequences, and other extensions in a 
section file (created with the SAVE EXTENDED EVE command). Use an EVE 
initialization file to set editing preferences or private defaults, such as margins 
and tabs, which are not saved in the section file. The following sections contain 
information about converting from EDT to EVE. 

A.10.1 Using the SET KEYPAD EDT Command 

The SET KEYPAD EDT command defines several keys to emulate EDT. You can 
put the command in your EVE initialization file or save the keypad setting in 
a section file. Most keypad functions work as in EDT, although the names may 
differ. For more information, see the online help topic called EDT Differences. 

A.10.2 Defining Keys for EVE Commands 

Use DEFI NE KEY commands to define keys that are not otherwise defined by 
SET KEYPAD EDT. Put the key-definition commands in your initialization file, or 
save the definitions in a section file. For example, the following sets of EDT and 
EVE key definitions are equivalent: 


In EDT: 


DEF 

KEY GOLD 2 

"EXT SHOW BUFFER 

DEF 

KEY GOLD 1 

"CHGLW. " 

DEF 

KEY GOLD u 

"CHGUW. " 

DEF 

KEY GOLD 10 

"EXT FIND=? . . " 

DEF 

KEY GOLD 9 

"CUTSR PASTE." 

DEF 

KEY cont n 

"EXT QUIT." 

DEF 

KEY func 34 

"SHL." 

In EVE: 


DEF 

KEY= GOLD E2 

SHOW BUFFERS 

DEF 

KEY= GOLD 1 

LOWERCASE WORD 

DEF 

KEY= GOLD U 

UPPERCASE WORD 

DEF 

KEY= GOLD PF2 

BUFFER 

DEF 

KEY= GOLD KP9 

STORE TEXT 

DEF 

KEY= Ctrl/N 

QUIT 

DEF 

KEY= F20 

SHIFT RIGHT 8 


Note the differences between EDT and EVE in some key names, as well as 
differences in command names. For more information about key names, see 
Section A. 2. 

A. 10.3 Setting Bound Cursor Motion 

Use the SET CURSOR BOUND command to enable an EDT style bound cursor. 
By default, EVE uses a free cursor, which you can move anywhere in the buffer. 
You can save the setting in your section file or DECTPU command file. 
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A.10.4 Setting the Right Margin for Wrapping Text 

Put the SET Rl GHT MARGI N command in your EVE initialization file to set a 
wrap limit for entering text and for FILL commands. For example, the following 
EDT and EVE commands are equivalent: 

I n E DT: 

SET WRAP 70 

In EVE: 

SET RIGHT MARGIN 70 

(The EVE command SET WRAP corresponds to the EDT command SET 
NOTRUNCATE.) 

A.10.5 Setting Scroll Margins for Moving the Cursor 

Put the SET SCROLL MARGI NS command in your EVE initialization file to set 
distances for scrolling to begin automatically as you move the cursor up or down. 
For example, with a 24-line terminal screen (21-line main window), the following 
EDT and EVE commands are equivalent: 

I n E DT: 

SET CURSOR 5:15 

In EVE: 

SET SCROLL MARGINS 5 6 

EVE scroll margins are measured from the top and bottom, respectively. In 
EDT, both scroll margins are measured from the top. You can specify numbers of 
lines or percentages of the window size. Also, the size of the EVE main window 
depends on your terminal settings. For example, on a workstation, the EVE main 
window may be longer than 21 lines. 

A.10.6 Setting Searches for Exact Case 

Searches follow EVE rules for case sensitivity. Put SET FIND commands in your 
EVE initialization file to set the way you want searches to work. For example, 
the following EDT and EVE commands are nearly equivalent: 

I n E DT: 

SET SEARCH EXACT 

In EVE: 

SET FIND CASE EXACT 

These commands are not exact equivalences because EVE always matches 
diacritical marks exactly as entered in the search string. 

A.10.7 Converting EDT Macros to DECTPU Procedures 

Use DECT PU procedures in place of EDT macros. Create a buffer that contains 
the procedures and then use EXTEND commands to compile the procedures 
with EXTEND commands. Or, put the procedures in a DECTPU command file 
and then use the /COMMAND qualifier to invoke EVE. In either case, you can 
save the compiled procedures in your section file. The following examples show 
a macro from an EDT startup file translated into a DECTPU procedure. Each 
creates a new command, WIDEN, which sets the display to 132 columns and sets 
the right margin to 120. 
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EDT Macro: 

FIND =WIDEN 
INSERT; SET SCREEN 132 
INSERT; SET WRAP 120 
FIND =MAIN. 

DECTPU Procedure: 

PROCEDURE EVE_WIDEN; 

EVE_SET_WIDTH (132); 

EVE_SET_RIGHT_MARGIN (120); 

ENDPROCEDURE; 

To execute the macro or procedure, use the following commands: 

In EDT: 

* DEFINE MACRO WIDEN 

* WIDEN 

In EVE: 

Command: EXTEND EVE WIDEN 
Command: WIDEN 

You can also use the LEARN command to bind the corresponding EVE commands 
to a single key. You can then save the key definition in your section file. Another 
method is to put the corresponding EVE commands in an initialization file. 

A.10.8 Converting EDT Nokeypad Statements to DECTPU Procedures 

You can usually convert EDT macros and key definitions that use nokeypad 
specifiers into DECTPU procedures or learn sequences. The following examples 
show an EDT key definition that uses nokeypad mode and the corresponding 
DECTPU procedure and key definition. In each case, you define Comma on the 
numeric keypad to transpose or swap the current and previous character. The -C 
in EDT nokeypad statements can be translated as MOVE_HORIZONTAL (-1) in 
DECTPU procedures. 

In EDT: 

DEFINE KEY 19 AS "-C D1C +C UNDO." 

In DECTPU: 

PROCEDURE USERJTRANSPOSE 
LOCAL SWAP_THIS; 

SWAPJIHIS := ERASE_CHARACTER (1); 

M0VE_H0RI ZONTAL (-1); 

EVE$INSERT_TEXT (SWAPJIHIS) ; 

RETURN (TRUE) ; 

ENDPROCEDURE; 

EVE$DEFINE_KEY ( "USERJTRANSPOSE" , COMMA, , EVE$X_USER_KEYS) ; 
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A.10.9 Using the WPS Keypad Ruler Key to Adjust Tab Stops 

Setting the EDT keypad does not define keys for EDT style tab adjustment. 
However, you can get similar effects by defining a key for the WPS keypad Ruler 
key (GOLD R) and then using the ruler to add or delete tab stops. 

For example, the following command defines F20 as the WPS Ruler key (without 
having to enable the WPS keypad): 

Command: DEFINE KEY= F20 WPS GOLD-R 

Then, to add or delete tab stops, follow these steps: 

1. Press whatever key you have defined as the Ruler key. 

EVE displays a ruler at the bottom of the current window (just above the 
status line for the window). The cursor appears in the ruler. Tab stops are 
marked with a T. 

2. Put the cursor where you want to add or delete a tab stop. For example, press 
the left and right arrow keys to move to a particular column in the ruler, or 
press the Tab key to move to the next tab stop (T) in the ruler. 

3. Type a T or t at that location to set the tab stop or, if there is already a tab 
there, to delete it. The new tab stops are immediately applied to the buffer 
you were editing. 

4. Repeat steps 2 and 3 to add or delete other tab stops. 

5. To exit from the ruler and resume editing, press the Return key or 
GOLD Return. 

For more information about the WPS Ruler key, including a list of the keys for 
moving the cursor in the ruler, see the description of the SET KEYPAD WPS 
command in the Guideto the Extensible Versatile Editor. 
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This appendix describes the DEC Multinational character set and the DCL 
character set. 

B.1 DEC Multinational Character Set 

The DEC Multinational character set is an 8-bit character set with 256 
characters; the first 128 characters in the set correspond to the ASCI I character 
set. Each character has a value in the range 0 to 255 decimal. 

Figure B-l represents the ASCI I character set (characters with decimal values 
0 through 127). The first half of each numbered column identifies the character 
as you would enter it on a VTxxx-series terminal or workstation, or as you would 
see it on a printer (except for the nonprintable characters). The remaining half 
of each column identifies the character by the binary value of the byte; the value 
is stated in three radixes— octal, decimal, and hexadecimal. For example, the 
uppercase letter A has, under ASCI I conventions, a storage value of hexadecimal 
41 (a bit configuration of 01000001), equivalent to 101 in octal notation and 65 in 
decimal notation. DCL uses hexadecimal values to perform string comparisons. 
(For a description of string comparisons, see Chapter 14.) 
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Figure B-1 Graphical Representation of the ASCII Character Set 
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Figure B-2 represents the second half of the DEC Multinational character 
set (characters with decimal values 128 through 255). The first half of each 
numbered column identifies the character as it appears on a VT200 or VT300 
series terminal or printer (you cannot display these characters on a VT100 series 
terminal). 
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Figure B-2 Graphical Representation of the DEC Multinational Extension to the ASCII 
Character Set 
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B.2 DCL Character Set 

Table B-l lists the characters in the DCL character set. 
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Table B-1 DCL Character Set 


Symbol 

Name 

Meaning 

@ 

At sign 

Places the contents of a command procedure file in the 
command input stream. 


Colon 

Device name delimiter in a file specification. A double colon 
(::) is a node name delimiter. A colon also acts as a qualifier 
delimiter. It separates a qualifier name from its value. 

/ 

Slash 

Qualifier prefix. 

+ 

Plus sign 

Parameter separator. With some commands it acts as a 
parameter concatenator. The plus sign is also recognized as 
a string concatenation operator, a unary plus sign, and an 
addition operator in a numeric expression. 


Comma 

List element separator for parameters or argument lists. 


H yphen 

Continuation character. The hyphen is also recognized as a 
string reduction operator, a unary minus sign, a subtraction 
operator in a numeric expression, and a directory-searching 
wildcard character. 

() 

Parentheses 

List delimiters for argument list. Parentheses are also used to 
indicate the order of operations in a numeric expression. 

[] 

Square 

brackets 

Directory name delimiters in a file specification. Equivalent to 
angle brackets. 

o 

Angle brackets 

Directory name delimiters in a file specification. Equivalent to 
square brackets. 

? 

Question mark 

Help character. 

& 

Ampersand 

Execution-time substitution operator. Otherwise, a reserved 
special character. 

\ 

Backslash 

Reserved special character. 


Equal sign 

Qualifier value delimiter. It separates a qualifier name from 
its argument. The equal sign ( =) can also be used as an 
assignment statement when defining symbols. 

/V 

Circumflex 

Reserved special character. 

# 

Number sign 

Reserved special character. 

* 

Asterisk 

Wildcard character in a file specification. The asterisk is also 
used as a multiplication operator in a numeric expression and 
as an abbreviation delimiter in a symbol definition. 

' 

Apostrophe 

Substitution operator. 


Period 

File type and version number delimiter in a file specification. 
Also used as a subdirectory delimiter. 


Semicolon 

Version number delimiter in a file specification. 

% 

Percent sign 

Wildcard character in a file specification. Also used as a radix 
operator. 

j 

Exclamation 

point 

1 ndicates a comment. 

i? 

Quotation 

mark 

Literal string delimiter. 
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This appendix contains complete command procedures that demonstrate the 
concepts and techniques discussed in Chapter 15 and Chapter 16. Each section 
in this appendix discusses one command procedure and contains the following 
information: 

• The name of the procedure 

• A listing of the procedure 

• Notes that explain concepts or techniques used by the procedure 

• The results of a sample execution of the procedure 
Table C-l summarizes the command procedures. 


Table C-1 Summary of Annotated Command Procedures 

Command Procedure Section Description 


CONVERT.COM Section C.l 


REMINDER.COM Section C.2 


DIR.COM Section C. 3 


SYS.COM Section C.4 


Converts an absolute time (for a time in the future) 
to a delta time, and determines the time between the 
current time and the time that you specify. The procedure 
illustrates the use of the F$TI M E andF$CVTIME lexical 
functions, and the use of assignment statements to perform 
arithmetic calculations and to concatenate symbol values. 

Displays a reminder message on your terminal at a 
specified time. The procedure prompts for the time you 
want the message to be displayed and for the text of the 
message. The procedureusesCONVERT.COM to convert 
the time to a delta time. The procedure then spawns a 
subprocess that waits until the specified time and displays 
your reminder message. The procedure illustrates the use 
of the F$ENVIRONMENT, F$VERI FY, and F$GETDVI 
functions. 

Imitates the DCL command D I RECTORY /SIZE =ALL 
/DATE, displaying the block size (used and allocated) and 
creation date of the specified files. It illustrates use of 
the F$PARSE, F$SEARCH, F$FILE_ATTRIBUTES, and 
F$FAO lexical functions. 

Returns statistics about the current process, all processes 
in the group (if the current process has group privilege), 
and all processes on the system (if the current process 
has world privilege). This procedure illustrates use of the 
F$PI D, F$EXTRACT, and F$GETJ PI lexical functions. 

(continued on next page) 
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Table C-1 (Cont.) Summary of Annotated Command Procedures 


Command Procedure 

Section 

Description 

GETPARMS.COM 

Section C.5 

Returns the number of parameters passed to a procedure. 
You can call GETPARMS.COM from another procedure 
to determine how many parameters were passed to the 
calling procedure. 

EDITALL.COM 

Section C.6 

Invokes the EDT editor repeatedly to edit a group of 
files with the same file type. This procedure illustrates 
how to use lexical functions to extract file names from 
columnar output. It also illustrates a way to redefine the 
input stream for a program invoked within a command 
procedure. 

MAILEDIT.COM 

Section C.7 

Invokes a text editor in the Mail utility. 

FORTUSER.COM 

Section C.8 

Provides a sample of a system-defined login command 
procedure that controls the terminal environment for 
an interactive user who creates, compiles, and executes 
FORTRAN programs. If a user logs into a captive account 
where FORTUSER.COM is listed as the login command 
procedure, the user can execute only the commands 
accepted by FORTUSER.COM. This procedure also 
illustrates how to use lexical functions to step through 
an option table, comparing a user-entered command with a 
list of valid commands. 

LISTER.COM 

Section C.9 

Prompts for input data, formats the data in columns, and 
sorts it into an output file. This procedure illustrates the 
READ and WRITE commands, as well as the character 
substring overlay format of an assignment statement. 

CALC.COM 

Section C.10 

Performs arithmetic calculations and converts the resulting 
value to hexadecimal and decimal values. 

BATCH.COM 

Section C.ll 

Accepts a command string, a command procedure, or a 
list of commands and then executes these commands as a 
batch job. 

COMPILE_FILE.COM 

Section C.12 

Compiles, links, and runs a file written in Pascal or 
FORTRAN. It prompts for a file to process and determines 
if the file type is .PAS or .FOR. If the file type is not .PAS 
or .FOR, or if the file does not exist in the current default 
directory, the command procedure outputs appropriate 
error messages. This procedure illustrates the use of the 
IF-THEN-ELSE language construct. 


C.1 CONVERT.COM Command Procedure 

$ ! Procedure to convert an absolute time to a delta time. 

$ ! The delta time is returned as the global symbol WAIT_TIME. 
$ ! PI is the time to be converted. 

$ ! P2 is an optional parameter - SHOW - that causes the 
$ ! procedure to display WAIT_TIME before exiting 
$ ! 

$ ! Check for inquiry 
$ ! 

$ IF PI . EQS. "?" .OR. PI . EQS. "" THEN GOTO TELL 1 
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$ ! 

$ ! Verify the parameter: hours must be less than 24 
$ ! minutes must be less than 60 

$ ! time string must contain only hours 

$ ! and minutes 

$ ! 

$ ! Change error and message handling to 
$ ! use message at BADTIME 
$ ! 

$ ON WARNING THEN GOTO BADTIME 2 

$ SAVEJ4ESSAGE = F$ENVIRONMENT ( "MESSAGE" ) 

$ SET MESSAGE/NOFACILITY/NOIDENTIFICATION/NOSEVERITY/NOTEXT 
$ TEMP = F$CVTIME (PI) 

$ ! 

$ ! Restore default error handling and message format 
$ ON ERROR THEN EXIT 
$ SET MESSAGE' SAVE_MESSAGE' 

S ! 

$ IF F$LENGTH (PI) .NE. 5 .OR. - 3 

F$LOCATE ( " : " , P 1 ) .NE. 2 - 
THEN GOTO BADTIME 

$ ! 

$ ! Get the current time 
$ ! 

$ TIME = F$TIME () 

$ ! 

$ ! Extract the hour and minute fields from both the 

$ ! value (TIME) and the future time (PI) 

S ! 

$ MINUTES = F$CVTIME (TIME, "ABSOLUTE", "MINUTE") 

$ HOURS = F$CVTIME (TIME, "ABSOLUTE", "HOUR") 

$ FUTURE_MINUTES = F$CVTIME (PI, "ABSOLUTE", "MINUTE") 

$ FUTUREJTOURS = F$CVTIME (PI, "ABSOLUTE", "HOUR") 

$ ! 

$ ! 

$ ! Convert both time values to minutes 

$ ! Note the implicit string to integer conversion being performed 

$ ! 

$ CURRENTJTIME = HOURS* 60 + MINUTES 6 

$ FUTUREJTIME = FUTURE_HOURS*60 + FUTURE_MINUTES 

S ! 

$ ! Compute difference between the future time and the current time 
$ ! (in minutes) 

S ! 

$ ! 

$ MINUTES_TO_WAIT = FUTUREJTIME - CURRENTJTIME 7 

S ! 

$ ! If the result is less than 0 the specified time is assumed to be 
$ ! for the next day; more calculation is required. 

$ ! 

$ IF MINUTES_TO_WAIT .LT. 0 THEN - 8 

MINUTES_TO_WAIT = 24*60 + FUTUREJTIME - CURRENTJTIME 

$ ! 

$ ! Start looping to determine the value in hours and minutes from 
S ! the value expressed all in minutes 
$ ! 

$ HOURS JTOJ/JAIT = 0 

$ H0URS_T0_WAIT_L00P : 9 

$ IF MINUTE SJT0_WAIT .LT. 60 THEN GOTO FINISHJCOMPUTE 

$ MINUTE S_T0_WAIT = MINUTES_TO_WAIT - 60 

$ HOURS JTOJVAIT = HOURSJTOJJAIT + 1 

$ GOTO HOURS JT0_WAIT_L00P 

$ FINISHJCOMPUTE : 


4 

current time 


! Current minutes 5 
! Current hours 
! Minutes in future time 
! Hours in future time 
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$ ! 

$ ! Construct the delta time string in the proper format 

$ ! 

$ WAITJTIME == F$STRING (HOURS_TO_WAIT) + + F$STRING (MINUTES_TO_WAIT) - 10 

+ " : 0 0 . 0 0 " 

$ ! 

$ ! Examine the second parameter 

$ ! 

$ IF P2 . EQS. "SHOW" THEN SHOW SYMBOL WAITJTIME 11 

$ ! 

$ ! Normal exit 

$ ! 

$ EXIT 

$ ! 

$ BADTIME: 12 

$ ! Exit taken if first parameter is not formatted correctly 
$ ! EXIT command returns but does not display error status 
$ ! 

$ SET MESSAGE' SAVE_MESSAGE' 

$ WRITE SYS$OUTPUT "Invalid time value: ",P1,", format must be hh:mm" 

$ WRITE SYS$OUTPUT "Hours must be less than 24; minutes must be less than 60" 

$ EXIT %X10000000 

$ ! 

$ ! 

$ TELL: 13 

$ ! Display message and exit if user enters inquiry or enters 
$ ! an illegal parameter 
$ ! 

$ TYPE SYS$INPUT 

This procedure converts an absolute time value to 
a delta time value. The absolute time must be in 
the form hh:mm and must indicate a time in the future. 

On return, the global symbol WAITJTIME contains the 
converted time value. If you enter the keyword SHOW 
as the second parameter, the procedure displays the 
resulting value in the output stream. To invoke this 
procedure, use the following syntax: 

@ CONVERT hh :mm [SHOW] 

$ EXIT 

Notes for CONVERT.COM Command Procedure 

1 The procedure checks whether the parameter was omitted or whether the 
value entered for a parameter is the question mark (?) character. In either 
case, the procedure branches to the label TELL. 

2 The procedure uses the F$CVTI ME function to verify that the time value 
is a valid 24-hour clock time; the F$CVTIME returns a warning message 
if the input time is not valid. If the F$CVTIME function returns an error, 
the procedure changes the default ON action to direct control to the label 
BADTIME. 

The procedure uses the F$ENVI RON M ENT function to save the current 
message setting. It then sets the message format so that no warning or 
error messages are displayed. After checking the time values, the procedure 
restores the default ON condition and message format. 

3 The procedure checks the format of the parameter. It must be a time value in 
the following format: 

hh:mm 


C-4 


Annotated Command Procedures 
C.1 CONVERT.COM Command Procedure 


The IF command checks (1) that the length of the entered value is 5 
characters and (2) that the third character (offset of 2) is a colon. The I F 
command contains the logical OR operator: if either expression is true (that 
is, if the length is not 5 or if there is not a colon in the third character 
position), the procedure branches to the label BADTI ME. 

4 The F$TIME lexical function places the current time value in the symbol 
TIME. 

5 The F$CVTI ME function extracts the "minute” and "hour" fields from the 
current time (saved in the symbol TIME). Then the F$CVTIME function 
extracts the "minute" and "hour" fields from the time you want to convert. 

6 These assignment statements convert the current and future times to 
minutes. When you use the symbols MINUTES, FI OURS, FUTURE_ 
HOURS, and FUTURE_MI NUTES in the assignment statements, the system 
automatically converts these values to integers. 

7 The procedure then subtracts the current time (in minutes) from the future 
time (in minutes). 

8 If the result is less than 0, the future time is interpreted as being on the next 
day. I n this case, the procedure adds 24 hours to the future time, and then 
subtracts the current time. 

9 The procedure enters a loop in which it calculates, from the value of 

Ml NUTES_TO_WAIT, the number of hours. Each time through the loop, 
it checks whether Ml NUTES_TO_WAIT is greater than 60. If it is, the 
procedure subtracts 60 from MINUTES_TO_WAIT and adds 1 to the 
accumulator for the number of hours (HOURS_TO_WAIT). 

10 When the procedure exits from the loop, it concatenates the hours and 
minutes values into a time string. The symbols HOURS_TO_WAIT and 

Ml NUTES_TO_WAIT are replaced by their character string equivalents and 
separated with an intervening colon. The resulting string is assigned to the 
symbol WAIT_TIME, which holds the delta time value for the future time. 
WAIT_TI M E is defined as a global symbol so that it is not deleted when the 
procedureCONVERT.COM exits. 

11 If a second parameter, SHOW, was entered, the procedure displays the 
resulting time value. Otherwise, it exits. 

12 At the label BADTIME, the procedure displays an error message that shows 
the incorrect value entered as well as the format it requires. After issuing the 
error message, CONVERT.COM exits. The EXIT command returns an error 
status in which the high-order digit is set to 1. This suppresses the display of 
an error message. 

The procedure explicitly specifies an error status with the EXIT command, 
so you can execute CONVERT.COM from within another procedure. When 
CONVERT.COM completes, the calling procedure can determine whether a 
time was successfully translated. 

13 At the label TELL, the procedure displays information about what the 
procedure does. TheTYPE command displays the lines listed in SYS$I NPUT, 
the input data stream. 
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Sample Execution for CONVERT.COM Command Procedure 

$ SHOW TIME 
10-JUN-1994 10:38:26 
$ @ CONVERT 12:00 SHOW 

WAIT_TIME = "1:22:00.00" 

The SHOW TIME command displays the current date and time. CONVERT.COM 
is executed with the parameters 12:00 and SHOW. The procedure converts the 
absolute time 12:00 to a delta time value and displays it on the terminal. 


C.2 REMINDER.COM Command Procedure 


Procedure to obtain a reminder message and display this 
message on your terminal at the time you specify. 

Save current states for procedure and image verification 
Turn verification off for duration of procedure 


SAVE_VERIFY_IMAGE = F$ENVIRONMENT ( "VERIFY_IMAGE" ) 
SAVE_VERIFY_PROC = F$VERIFY(0) 


1 


Places the current process in a wait state until a specified 
absolute time. Then, it rings the bell on the terminal and 
displays a message. 

Prompt for absolute time 


GET_TIME : 

INQUIRE REMINDER_TIME "Enter time to send reminder (hh:mm)" 2 
INQUIRE MESSAGEJTEXT "Enter message" 

Call the CONVERT.COM procedure to convert the absolute time 
to a delta time 

0DISK2: [JONES. TOOLS] CONVERT ' REMINDER_TIME' 3 

IF .NOT. $STATUS THEN GOTO BADTIME 


Create a command file that will be executed 
in a subprocess. The subprocess will wait until 
the specified time and then display your message 
at the terminal. If you are working at a DEC_CRT 
terminal, the message has double size blinking 
characters. Otherwise, the message has normal letters. 
In either case, the terminal bell rings when the 
message is displayed. 


! Lines starting with $ are data lines 


CREATE WAKEUP.COM 
DECK 

WAIT 'WAIT_TIME' 5 

BELL [0,7] = %X07 ! Create symbol to ring the bell 

IF F$GETDVI ("SYS$OUTPUT", "TT_DECCRT") .NES. "TRUE" THEN GOTO OTHER_TERM 

i 

DEC_CRT_ONLY : 

! Create symbols to set special graphics (for DEC_CRT terminals only) 


SET_FLASH = "<ESC>[l;5m" 
SET_NOFLASH = "<ESC>[0m" 
TOP = "<ESC>#3" 

BOT = "<ESC>#4" 


! Turn on blinking characters 
! Turn off blinking characters 
! Double size characters (top portion) 

! Double size characters (bottom portion) 
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$ ! 

$ ! Write double size, blinking message to the terminal and ring the bell 
$ ! 

$ WRITE SYS$OUTPUT BELL, SET_FLASH, TOP, MESSAGE_TEXT 

$ WRITE SYS$OUTPUT BELL, BOT, MESSAGE_TEXT 

$ WRITE SYS$OUTPUT F$TIME(), SET_NOFLASH 

$ GOTO CLEAN_UP 

$ ! 

$ OTHER_TERM: 

$ WRITE SYS$OUTPUT BELL, MESSAGE_TEXT 

$ WRITE SYS$OUTPUT F$TIME () 

S ! 

$ CLEAN_UP : 

$ DELETE WAKEUP.COM;* 

$ EOD 
$ ! 

$ ! Now continue executing commands. 

S ! 

$ SPAWN/NOWAIT/lNPUT=WAKEUP . COM 6 

$ END : 7 

$ ! Restore verification 

$ SAVE_VERIFY_PROC = F$VERIFY (SAVE_VERIFY_PROC, SAVE_VERIF Y_IMAGE ) 

$ EXIT 

$ ! 

$ BADTIME: 

$ WRITE SYS$OUTPUT "Time must be entered as hh:mm" 

$ GOTO GET_TIME 

Notes for REMINDER.COM Command Procedure 

1 The procedure uses the F$ENVIRONMENT function to save the image 
verification setting in the symbol SAVE_VERIFY_IMAGE. Next, the 
procedure uses the F $VE Rl F Y function to save the procedure verification 
setting in the symbol SAVE_VERIFY_PROC. The F$VERIFY function also 
turns off both types of verification. 

2 The procedure uses the I NQUI RE command to prompt for the time when 
the reminder message should be sent. This value is used as input to the 
procedure CONVERT.COM. The procedure also prompts for the text of the 
message. 

3 The procedure executes a nested procedure, CONVERT.COM. Be sure to 
specify the disk and directory as part of the file specification; this ensures 
that the system can locate CONVERT.COM regardless of the directory from 
which you execute REMINDER.COM. 

CONVERT.COM converts your reminder to a delta time, and returns this 
time in the global symbol WAIT_TI ME. This delta time indicates the time 
interval from the current time until the time when the message should be 
sent. lfCONVERT.COM returns an error, the procedure branches to the label 
BADTIME. 

4 The procedure uses the CREATE command to create a new procedure, 
WAKEUP.COM. This procedure is executed from within a subprocess. To 
allow the CREATE command to read lines that begin with dollar signs, 
use the DECK and EOD commands to surround the input for the CREATE 
command. Therefore, all lines between the DECK and EOD commands are 
written toWAKEUP.COM. 

5 WAKEUP.COM performs the following tasks: 

• It waits until the time indicated by the symbol WAIT_TI ME. 

• 1 1 creates the symbol BELL to ri ng the termi nal bel I . 
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• It determines whether the terminal is a DEC_CRT terminal and can 
accept escape sequences to display double-size, blinking characters. (To 
see whether you have a DEC_CRT terminal, enter the SHOW TERM I NAL 
command and see whether this characteristic is listed.) 

• If the terminal is a DEC_CRT terminal, then the procedure defines the 
symbols SET_FLASH, TOP, and BOT. These symbols cause the terminal 
to use flashing, double-size characters. The procedure also defines the 
symbol SET_NOFLASH to return the terminal to its normal state. To 
enter the escape character (<ESC>) when you create these definitions 
using the EDT editor, press the ESC key twice. 

After defining these symbols, the procedure writes three lines to the 
terminal. The first line rings the bell, turns on flashing characters, and 
displays (using double-size characters) the top half of your message. The 
second line rings the bell again, and displays the bottom half of your 
message. The third line writes the current time and then turns off the 
flash characteristic to return your terminal to normal. 

If you do not have a DEC_CRT terminal, then the procedure rings your 
terminal bell, and displays your message and the time. 

• The DELETE command causes the procedure WAKEUP.COM to delete 
itself after it executes. 

6 After creating WAKEUP.COM, the procedure spawns a subprocess and directs 
the subprocess to use WAKEUP.COM as the input command file. The 
/NOWAIT qualifier allows you to continue working at your terminal while 
the subprocess executes commands from WAKEUP.COM. At the specified 
time, WAKEUP.COM displays your message on your terminal. 

Note that, by default, the SPAWN command passes global and local symbols 
to a subprocess. Therefore, although you provide values for the symbols 
WAIT_TI ME and MESSAGE_TEXT in REMINDER.COM, WAKEUP.COM can 
also access these symbols. 

7 The procedure restores the original verification settings before it exits. 

Sample Execution for REMINDER.COM Command Procedure 

$ @ REMINDER 

Enter time to send reminder (hh:mm) : 12:00 

Enter message: TIME FOR LUNCH 

%DCL-S-SPAWNED, process BLUT0_1 spawned 

$ 


TIME FOR LUNCH 
ll-DEC-1994 12:00:56.99 

The procedure prompts for a time value and for your message. Then the 
procedure spawns a subprocess that displays your message. You can continue 
working at your terminal; at the specified time, the subprocess rings the terminal 
bell, displays your message, and displays the time. 
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C.3 DIR.COM Command Procedure 

$ ! 

$ ! Command procedure implementation of DIRECTORY/SIZE=ALL/DATE 
$ ! command 
$ ! 

$ SAVE_VERIFY_IMAGE = F$ENVIRONMENT ( "VERIFY_IMAGE" ) 

$ SAVE_VERIFY_PROCEDURE = F$VERIFY(0) 

$ ! 

$ ! Replace any blank field of the PI file specification with 
$ ! a wildcard character 
$ ! 

$ PI = F$PARSE (PI, "*.*;*") 1 

$ ! 

$ ! Define initial values for symbols 

$ ! 

$ FIRSTJIIME = "TRUE" 

$ FILE_COUNT = 0 
$ TOTAL_ALLOC = 0 
$ TOTALISED = 0 
$ 

$ LOOP : 2 

$ FILESPEC = F$SEARCH (PI ) 

$ ! Find next file in directory 
$ IF FILESPEC . EQS. "" THEN GOTO DONE 

$ ! If no more files, then done 
$ IF .NOT. FIRST_TIME THEN GOTO SHOW_FILE 

$ ! Print header only once 

$ ! 

$ ! Construct and output the header line 

$ ! 

$ FIRST_TIME = "FALSE" 3 

$ DIRSPEC = F$PARSE (FILESPEC,,, "DEVICE") - 

+F$PARSE (FILESPEC, , , "DIRECTORY") 

$ WRITE SYS$OUTPUT "" 

$ WRITE SYS$OUTPUT "Directory ", DIRSPEC 

$ WRITE SYS$OUTPUT "" 

$ LASTDIR = DIRSPEC 

$ 

$ ! 

$ ! Put the file name together, get some of the file attributes, and 
$ ! type the information out 
$ ! 

$SHOW_FILE : 

$ FILEJCOUNT = FILE_COUNT + 1 

$ FILENAME = F$PARSE (FILESPEC,,, "NAME") - 4 

+ F$PARSE (FILESPEC,,, "TYPE") - 
+ F$PARSE (FILESPEC,,, "VERSION") 

$ ALLOC = F$FILE_ATTRIBUTES (FILESPEC, "ALQ" ) 

$ USED = F$FILE_ATTRIBUTES (FILESPEC, "EOF") 

$ TOTAL_ALLOC = TOTAL_ALLOC + ALLOC 

$ TOTALISED = TOTALISED + USED 

$ REVISED = F$FILE_ATTRIBUTES (FILESPEC, "RDT") 

$ LINE = F$FAO ( " ! 19AS ! 5UL/ ! 5< !UL ! > ! 17AS", FILENAME, - 

USED, ALLOC, REVISED) 

$ WRITE SYS$OUTPUT LINE 

$ GOTO LOOP 

$ 
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$ ! 

$ ! Output summary information, reset verification, and exit 
$ ! 

$ DONE : 5 

$ WRITE SYS$OUTPUT "" 

$ WRITE SYS$OUTPUT "Total of "FILE_COUNT' files, ” + - 

" ' ' TOTALISED' /' ' TOTAL_ALLOC' blocks . " 

$ SAVE_VERIFY_PROCEDDRE = F$VERIFY (SAVE_VERIFY_PROCEDURE, SAVE_VERIFY_IMAGE) 

$ EXIT 


Notes for DIR.COM Command Procedure 

1 This procedure uses the F$PARSE function to place asterisks in blank fields 
in PI, the user-supplied file specification. If you do not specify a parameter 
when you execute DIR.COM, then the F$PARSE function assigns the value 
"*.*;*” to PI. ThiscausesDIR.COM to display all files in the current default 
directory. 

2 The F$SEARCFI lexical function searches the directory for the file (or 
files) indicated by PI. If PI contains any wildcards (asterisks), the 
F$SEARCFI function returns all matching file specifications. After the last file 
specification has been returned, the procedure branches to the label DONE. 

3 The first time through the loop, the procedure writes a header for the 
directory display. This header includes the device and directory names. 

To obtain these names, the procedure uses the F$PARSE function. 

4 The procedure uses the F$PARSE lexical function to extract the file name 
from each file specification in the directory. The F$FILE_ATTRIBUTES 
lexical function then obtains blocks used, blocks allocated, and creation date 
information about each file. Finally, the F$FAO function formats a single 
display line for each file in the directory. The F$FAO function uses the file 
name and file attribute information as arguments. 

5 When F$SEARCFI returns a null string, the procedure branches to the label 
DONE and displays summary information showing the total number of files, 
the total number of blocks used, and the total number of blocks allocated in 
the directory. 

Sample Execution for DIR.COM Command Procedure 

$ @DIR [VERN] * . COM 


Directory DISK4 : [VERN] 


BATCH.COM; 1 

1/3 

ll-DEC-1994 11:43 

CALC.COM; 3 

1/3 

ll-DEC-1994 11:30 

CONVERT . COM; 1 

5/6 

ll-DEC-1994 15:23 


LOGIN.COM; 34 

2/3 

ll-DEC-1994 13:17 

PID.COM; 7 

1/3 

ll-DEC-1994 09:49 

SCRATCH . COM; 6 

1/3 

ll-DEC-1994 11:29 


Total of 15 files, 22/48 blocks. 

The procedure returns information on all .COM files in the directory [VERN], 
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C.4 SYS.COM Command Procedure 

$ ! 

$ ! Displays information about owner, group, or system processes. 

$ ! 

$ ! Turn off verification and save current settings 
$ SAVE_VERIFY_IMAGE = F$ENVIRONMENT ( "VERIFY_IMAGE" ) 

$ SAVE_VERIFY_PROCEDURE = F$VERIFY(0) 

$ CONTEXT = "" ! Initialize PID search context 1 

$ ! 

$ ! Output header line. 

$ ! 

$ WRITE SYS$OUTPUT " PID Username Term Process " + - 2 

"name State Pri Image" 

$ ! 

$ ! Output process information. 

$ ! 

$LOOP : 

$ ! 

$ ! Get next PID. If null, then done. 

$ ! 

$ PID = F$PID (CONTEXT) 3 

$ IF PID .EQS . "" THEN GOTO DONE 

$ ! 

$ ! Get image file specification and extract the file name. 

$ ! 

$ IMAGNAME = F$GETJPI (PID, " IMAGNAME" ) 4 

$ IMAGNAME = F$PARSE ( IMAGNAME, ,, "NAME" , "SYNTAX_ONLY" ) 

$ ! 

$ ! Get terminal name. If none, then describe type of process. 

$ ! 

$ TERMINAL = F$GETJPI (PID, "TERMINAL") 5 

$ IF TERMINAL .EQS. "" THEN - 

TERMINAL = "-"+F$EXTRACT (0, 3, F$GETJPI (PID, "MODE" ) ) 

$ IF TERMINAL .EQS. "-INT-" THEN TERMINAL = "-DET-" 

$ IF F$GETJPI (PID, "OWNER") ,NE . 0 THEN TERMINAL = "-SUB-" 

$ ! 

$ ! Get some more information, put process line together, 

$ ! and output it . 

$ ! 

$ LINE = F$FAO ( " ! AS 112AS ! 7AS ! 15AS ! 5AS 12UL/1UL 110AS", - 6 

PID, F$GETJPI (PID, "USERNAME") , TERMINAL, - 
F$GETJPI (PID, "PRCNAM") , - 

F$GETJPI (PID, "STATE") ,F$GETJPI (PID, "PRI") ,- 
F$GETJPI (PID, "PRIB") , IMAGNAME) 

$ WRITE SYS$OUTPUT LINE 

$ GOTO LOOP 

$ ! 

$ ! Restore verification and exit. 

$ ! 

$DONE : 

$ SAVE_VERIFY_PROCEDURE = F$VERIFY (SAVE_VERIFY_PROCEDURE, SAVE_VERIFY_IMAGE) 
$ EXIT 


Notes for SYS.COM Command Procedure 

1 The symbol CONTEXT is initialized with a null value. This symbol will 
be used with the F$PID function to obtain a list of process identification 
numbers. 

2 The procedure writes a header for the display. 
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3 The procedure gets the first process identification (PI D) number. If the 
current process lacks group or world privilege, the PI D number of the current 
process is returned. If the current process has group privilege, the first PI D 
number in the group list is returned. The first PID number in the system list 
is returned if the current process has world privilege. The function continues 
to return the next PID number in sequence until the last PID number is 
returned. At this point, a null string is returned, and the procedure branches 
to the end. 

4 The procedure uses the F$GETJ PI lexical function to get the image file 
specification for each PID number. TheF$PARSE function extracts the file 
name from the specification returned bytheF$GETJ PI function. 

5 The procedure uses the F$GETJ PI function to get the terminal name for each 
PI D number. The F $EXTRACT function extracts the first three characters of 
the MODE specification returned by F$GETJ PI (PI D,"MODE") to determine 
the type of process. The F$GETJ PI function is used again to determine 
whether the process is a subprocess. 

6 The procedure uses the F$GETJ PI lexical function to get the user name, 
process name, process state, process priority, and process base priority 
for each PID number returned. The F$FAO lexical function formats this 
information into a screen display. 

Sample Execution for SYS.COM Command Procedure 

$ @SYS 


PID Username Term Process name State Pri Image 


00050011 NETN0NPRIV -NET- 
00040013 STOVE RTA6 : 
00140015 MAROT -DET- 
00080016 THOMPSON -DET- 
00070017 JUHLES TTF1 : 


00040018 MARCO TTA2 : 
0018001A VERN RTA3 : 
0033001B YISHA RTA7 : 
0002004A SYSTEM -DET- 


MAIL_14411 

LEF 

9/4 

MAIL 

STOVE 

LEF 

9/4 


DMFBOACP 

HIB 

9/8 

F11BAC 

MTA0ACP 

HIB 

12/8 

MTAAACP 

JUHLES 

LEF 

9/4 



MARCO 

HIB 

9/4 

RTPAD 

VERN 

LEF 

9/4 


YISHA 

CUR 

4/4 


ERRFMT 

HIB 

12/7 

ERRFMT 


This procedure returns information on all processes on the system. The current 
process has world privilege. 


C.5 GETPARMS.COM Command Procedure 

$ ! Procedure to count the number of parameters passed to a command 
$ ! procedure. This number is returned as the global symbol PARMCOUNT. 
$ ! 

$ SAVE_VERIFY_IMAGE = F$ENVIRONMENT ( "VERIFY_IMAGE" ) 1 

$ SAVE_VERIFY_PROCEDURE = F$VERIFY(0) 

$ ! 

$ IF PI . EQS. "?" THEN GOTO TELL 2 

$ ! 

$ ! Loop to count the number of parameters passed. Null parameters are 
$ ! counted until the last non-null parameter is passed. 

$ ' 
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$ COUNT =0 3 

$ LASTNONNULL = 0 

$ LOOP: 

$ IF COUNT .EQ. 8 THEN GOTO END_C0UNT 

$ COUNT = COUNT + 1 

$ IF P' COUNT' .NES. "" THEN LASTNONNULL = COUNT 

$ GOTO LOOP 
$ ! 

$ END_COUNT : 4 

$ ! 

$ ! Place the number of non-null parameters passed into PARMCOUNT. 

S ! 

$ PARMCOUNT == LASTNONNULL 
$ ! 

$ ! Restore verification setting, if it was on, before exiting 
$ ! 

$ SAVE_VERIFY_PROCEDURE = F$VERIFY (SAVE_VERIFY_PROCEDURE, SAVE_VERIFY_IMAGE) 5 
$ EXIT 
$ ! 

$ TELL: 6 

$ TYPE SYS$INPUT 

This procedure counts the number of parameters passed to 
another procedure. This procedure can be called by entering 
the string: 

0GETPARMS 'PI ' P2 'P3 'P4 'P5 ' P6 'P7 ' P8 
in any procedure. On return, the global symbol PARMCOUNT 
contains the number of parameters passed to the procedure. 

$ ! 

$ EXIT 

Notes for GETPARMS.COM Command Procedure 

1 The procedure saves the current image and procedure verification settings 
before turning off verification. 

2 If a question mark character was passed to the procedure as a parameter, the 
procedure branches to the label TELL (Note 6). 

3 A loop is established to count the number of parameters that were passed 
to the procedure. The counters COUNT and LASTNONNULL are initialized 
to 0 before entering the loop. Within the loop, COUNT is incremented and 
tested against the value 8. If COUNT is equal to 8, the maximum number 
of parameters has been entered. Each time a non-null parameter is passed, 
LASTNONNULL is equated to that parameter's number. 

Each time the I F command executes, the symbol COUNT has a different 
value. The first time, the value of COUNT is 1 and the I F command checks 
PI. The second time, it checks P2, and so on. 

4 When the parameter count reaches 8, the procedure branches to END_ 
COUNT. The symbol LASTNONNULL contains the count of the last non-null 
parameter passed. This value is placed in the global symbol PARMCOUNT. 
PARMCOUNT must be defined as a global symbol so that its value can be 
tested at the calling command level. 

5 The original verification settings are restored. 

6 At the label TELL, the TYPE command displays data that is included in the 
input stream. (In command procedures, the input stream is the command 
procedure file.) The TYPE command displays instructions on how to use 
GETPARMS.COM. 
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Sample Execution for GETPARMS.COM Command Procedure 

The procedure SORTFILES.COM requires the user to pass three non-null 
parameters. TheSORTFILES.COM procedure can contain the following lines: 

$ @ GETPARMS 'PI' ' P2' 'P3' 'P4' 'P5' 'P6' 'P7' 'P8' 

$ IF PARMCOUNT .NE. 3 THEN GOTO NOT_ENOUGH 


$NOT_ENOUGH : 

$ WRITE SYS$OUTPUT - 

"Three non-null parameters required. Type SORTFILES HELP for info." 

$ EXIT 

The procedure SORTFILES.COM can be invoked as follows: 

$ @ SORTFILES DEF 4 

Three non-null parameters required. Type SORTFILE HELP for info. 

For this procedure to be properly invoked— that is, for the parameters that are 
passed to SORTFILES to be passed intact to GETPARMS for processing— the 
symbols PI to P8 must be enclosed in single quotation marks. 

If the return value from GETPARMS is not 3, SORTFILES outputs an error 
message and exits. 

C.6 EDITALL.COM Command Procedure 

$ ! Procedure to edit all files in a directory with a 
$ ! specified file type. Use PI to indicate the file type. 

$ ! 

$ ON CONTROL_Y THEN GOTO DONE ! Ctrl/Y action 1 

$ ON ERROR THEN GOTO DONE 

$ ! 

$ ! Check for file type parameter. If one was entered, continue; 

$ ! otherwise, prompt for a parameter. 

$ ! 

$ IF PI .NES. "" THEN GOTO OKAY 2 

$ INQUIRE PI "Enter file type of files to edit" 

$ ! 

$ ! List all files with the specified file type and write the DIRECTORY 
$ ! output to a file named DIRECT. OUT 
$ ! 

$ OKAY: 

$ DIRECTORY/VE RSI0NS=1/C0LUMNS=1 - 3 

/NODATE/NOSIZE - 
/NOHEADING/NOTRAILING - 
/OUTPUT=DIRECT . OUT *.'P1' 

$ IF .NOT. $ STATUS THEN GOTO ERROR_SEC 4 

$ ! 

$ OPEN/READ/ERROR=ERROR_SEC DIRFILE DIRECT. OUT 5 

$ ! 

$ ! Loop to read directory file 

$ ! 
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$ NEWLINE: 

$ READ/END=DONE DIRFILE NAME 

$ DEFINE/USERJ40DE SYS$INPUT SYS $ COMMAND : 

$ EDIT 'NAME' 

$ GOTO NEWLINE 

S ! 

$ DONE: 

$ CLOSE DIRFILE/ERROR=NOTOPEN 

$ NOTOPEN: 

S DELETE DIRECT. OUT;* 

$ EXIT 

S ! 

$ ERROR_SEC: 

$ WRITE SYS$OUTPUT "Error: 

$ DELETE DIRECT. OUT;* 

$ EXIT 


! Redefine SYS$INPUT 
! Edit the file 


! Close the file 
! Delete temp file 


1 , F$MESSAGE ($ STATUS) 


Notes for EDITALL.COM Command Procedure 


1 ON commands establish condition handling for this procedure. If Ctrl/Y is 
pressed at any time during the execution of this procedure, the procedure 
branches to the label DONE. Similarly, if any error or severe error occurs, the 
procedure branches to the label DONE. 

2 The procedure checks whether a parameter was entered. If not, the procedure 
prompts for a file type. 

3 The Dl RECTORY command lists all files with the file type specified as PI. 
The command output is written to the file Dl RECT.OUT. The /VERSI 0NS=1 
qualifier requests that only the highest numbered version of each file be 
listed. The /NOH EADI NG and /NOTRAI LI NG qualifiers request that 

no heading lines or directory summaries be included in the output. The 
/C0LUMNS=1 qualifier ensures that one file name per record is given. 

4 The I F command checks the return value from the Dl RECTORY command 
by testing the value of $STATUS. If the Dl RECTORY command does not 
complete successfully, then $STATUS has an even integer value, and the 
procedure branches to the label ERROR_SEC. 

5 The OPEN command opens the directory output file and gives it a logical 
name of Dl RFI LE. 


6 The READ command reads a line from the Dl RECTORY command output 
into the symbol name NAME. After it reads each line, the procedure uses 
the DEFI NE command to redefine the input stream for the edit session 
(SYS$I N PUT) to be the terminal. Then, it invokes the editor, specifying the 
symbol NAME as the file specification. When the edit session is completed, 
the command interpreter reads the next line in the command procedure and 
branches to the label NEWLI NE. When the procedure has edited all files of 
the specified file type in the directory, it branches to the label DONE. 

7 The label DONE is the target label for the /END qualifier on the READ 
command and the target label for the ON CONTROL_Y and ON ERROR 
conditions set at the beginning of the procedure. At this label, the procedure 
performs the necessary cleanup operations. 

The CLOSE command closes the DIRECTORY command output file; the 
/ERROR qualifier specifies the label on the next line in the file. This use 
of /ERROR suppresses any error message that would be displayed if the 
directory file is not open. For example, this would occur if Ctrl/Y were pressed 
before the directory file were opened. 
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The second step in cleanup is to delete the temporary directory file. 

Sample Execution for EDITALL.COM Command Procedure 

$ 0EDITALL DAT 


%DELETE-I-FILDEL, device : [directory] DIRECT .OUT; 1 deleted (x blocks) 

The procedure EDI TALL is invoked with PI specified as .DAT. The procedure 
creates a directory listing of all files in the default directory whose file types are 
.DAT and invokes the editor to edit each one. After you finish editing the last file 
with the file type .DAT, the procedure deletes the temporary file Dl RECT.OUT 
and displays an informational message at your terminal. 

C.7 MAILEDIT.COM Command Procedure 

$ ! Command procedure to invoke an editor for Mail. 

$ ! 

$ ! Inputs: 

$ ! 

$ ! PI = Input file name. 

$ ! P2 = Output file name. 

$ ! 

$ ! If MAIL$EDIT is undefined, Mail will invoke the user's selected callable 
$ ! editor set by the mail SET EDITOR command. 

$ ! 

$ ! If MAIL$EDIT is defined to be a command procedure, Mail will create 
$ ! a subprocess to edit the mail, but any SET EDITOR command in Mail 
$ ! will override the definition of MAIL$EDIT for the remainder of that 
$ ! Mail session. 

$ ! 

$ ! Note that this procedure is run in the context of a subprocess. 

$ ! LOGIN.COM is not executed. However, all process logical names 
$ ! and DCL global symbols are copied. In particular, note that the user's 
$ ! individual definition of the symbol EDIT is used if there is one. 

$ ! Otherwise, the system default editor is used. 

$ ! 

$ ! The default directory is the same as the parent process 
$ ! 

$ DEFINE /USER SYS$INPUT ' F$TRNLNM ( "SYS$OUTPUT" ) ' 1 

$ IF PI . EQS. "" THEN GOTO NOINPUT 2 

$ EDIT /0UTPUT='P2' 'PI' 3 

$ EXIT 
$N0INPUT : 

$ EDIT ' P2' 4 

$ EXIT 

Notes for MAILEDIT.COM Command Procedure 

1 The DEFINE command allows the editor input to come from the terminal 
instead of the command file. 

2 The I F statement distinguishes between editing a file with a different output 
file name from editing a file with the same file name. 

3 This EDIT command invokes an editor with input and output file names. You 
can edit this line to invoke an editor of your choice. For example: 

$ RUN XYZ_EDITOR.EXE /INPUT= 'PI' /0UTPUT='P2' 

4 This EDIT command invokes an editor with a single file name. You can edit 
this line to invoke an editor of your choice. For example: 

$ RUN XYZ_EDITOR.EXE /INPUT= 'P2' /0UTPUT='P2' 
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Sample Execution for MAILEDIT.COM Command Procedure 

$DEFINE MAIL$EDIT MAILEDIT.COM 
$MAIL 

MAIL> SHOW EDITOR 

Your editor is defined by the file MAILEDIT.COM. 


C.8 FORTUSER.COM Command Procedure 

$ ! Procedure to create, compile, link, execute, and debug 
$ ! FORTRAN programs. Users can enter only the commands listed 
$ ! in the symbol OPTION_TABLE . 

$ SET NOCONTROL=Y 1 

$ SAVE_VERIFY_IMAGE = F$ENVIRONMENT ( "VERIFY_IMAGE" ) 

$ SAVE_VERIFY_PROCEDURE = F$VERIFY(0) 

$ OPTION_TABLE = "EDIT/COMPILE/LINK/RUN/EXECUTE/DEBUG/PRINT/HELP/FILE/DONE/" 2 
$ TYPE SYS$INPUT 3 


VMS FORTRAN Command Interpreter 


Enter name of file with which you would like to work. 

$ ! 

$ ! Set up for initial prompt 
$ ! 

$ PROMPT = "INIT" 4 

$ GOTO HELP ! Print the initial help message 

$ ! 

$ ! after the first prompting message, use the prompt: Command 
$ ! 

$ INIT: 

$ PROMPT = "GETJCOMMAND" 

$ GOTO FILE ! Get initial file name 

$ ! 

$ ! Main command parsing routine. The routine compares the current 
$ ! command against the options in the option table. When it finds 
$ ! a match, it branches to the appropriate label. 

$ ! 

$ GET_COMMAND : 

$ ON CONTROL_Y THEN GOTO GET_COMMAND ! Ctrl/Y resets prompt 5 

$ SET CONTROL=Y 

$ ON WARNING THEN GOTO GETJCOMMAND ! If any, reset prompt 

$ INQUIRE COMMAND "Command" 

$ IF COMMAND . EQS. "" THEN GOTO GETJCOMMAND 

$ IF F$ LOCATE (COMMAND + "/", OPTION JTABLE) .EQ. F$LENGTH (OPTIONJTABLE) 

THEN GOTO INVALID JCOMMAND 

$ GOTO 'COMMAND' 

$ ! 

$ INVALID JCOMMAND : 7 

$ WRITE SYS$OUTPUT " Invalid command" 

$ ! 

$ HELP : 8 

$ TYPE SYS$INPUT 


The commands you can enter are: 

FILE Name of FORTRAN program in your current 

default directory. Subsequent commands 
process this file. 

EDIT Edit the program. 

COMPILE Compile the program with FORTRAN. 

LINK Link the program to produce an executable image. 

RUN Run the program's executable image. 

EXECUTE Same function as COMPILE, LINK, and RUN. 

DEBUG Run the program under control of the debugger. 

PRINT Queue the most recent listing file for printing. 

DONE Return to interactive command level. 

HELP Print this help message. 


- 6 
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Enter Ctrl/Y to restart this session 
$ GOTO 'PROMPT' 9 

$ EDIT: 10 

$ DEFINE /USER_MODE SYS$INPUT SYS$COMMAND : 

$ EDIT 'FILE_NAME' .FOR 

$ GOTO GET_COMMAND 

$ COMPILE: 

$ FORTRAN 'FILE_NAME' /LIST/OBJECT/DEBUG 

$ GOTO GETJCOMMAND 

$ LINK: 

$ LINK 'FILE_NAME' /DEBUG 

$ PURGE ' FILE_NAME' . */KEEP=2 

$ GOTO GETJCOMMAND 

$ RUN: 

$ DEFINE/USER_MODE SYS$INPUT SYS$COMMAND : 

$ RUN/NODEBUG ' FILE_NAME' 

$ GOTO GETJCOMMAND 

$ DEBUG: 

$ DEFINE /USER_MODE SYS$INPUT SYS$COMMAND : 

$ RUN ' FILE_NAME' 

$ GOTO GET_COMMAND 

$ EXECUTE: 

$ FORTRAN 'FILENAME' /LIST/OBJECT 

$ LINK/DEBUG ' FILE_NAME' 

$ PURGE ' FILE_NAME' . */KEEP=2 

$ RUN/NODEBUG ' FILE_NAME' 

$ GOTO GET_COMMAND 

$ PRINT: 

$ PRINT ' FILE_NAME' 

$ GOTO GET_COMMAND 

$ BADFILE: 11 

$ WRITE SYS$OUTPUT "File must be in current default directory." 

$ FILE: 

$ INQUIRE FILE_NAME "File name" 

$ IF FILE_NAME . EQS. "" THEN GOTO FILE 

$ IF F$PARSE(FILE_NAME, ,, "DIRECTORY") .NES. F$DIRECTORY () - 12 

THEN GOTO BADFILE 

$ FILE_NAME = F$PARSE (FILE_NAME, , , "NAME") 

$ GOTO GETJCOMMAND 

$ DONE: 

$ EXIT 


Notes for FORTUSER.COM Command Procedure 

1 The SET NOCONTROL =Y command ensures that the user who logs in under 
the control of this procedure cannot interrupt the procedure or any command 
or program in it. 

2 The option table lists the commands that the user will be allowed to execute. 
Each command is separated by a slash. 

3 The procedure introduces itself. 

4 The symbol name PROMPT is given the value of a label in the procedure. 
When the procedure is initially invoked, this symbol has the value I NIT. 

The HELP command text terminates with a GOTO command that specifies 
the label PROMPT. When this text is displayed for the first time, the GOTO 
command results in a branch to the label HELP. This displays the HELP 
message that explains the commands that you can enter. Then, the procedure 
branches back to the label INIT, where the value for PROMPT is changed 

to "GET_COM MAN D." Finally, the procedure branches to the label FILE to 
get a file name. Thereafter, when the help text is displayed, the procedure 
branches to the label GET_COMMAND to get the next command. 
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5 The Ctrl/Y condition action is set to return to the label GET_COMMAND, as 
is the warning condition action. The procedure prompts for a command and 
continues to prompt, even if nothing is entered. To terminate the session and 
return to interactive command level, enter the command DONE. 

6 The procedure uses the F$LOCATE and F$LENGTH lexical functions 
to determine whether command is included in the list of options. The 
F$LOCATE function searches for the user-entered command, followed by 

a slash. (For example, if you enter EDIT, the procedure searches for EDIT/.) 
If the command is not included in the option list, then the procedure branches 
to the label I NVALI D_COMMAND. If the command is valid, the procedure 
branches to the appropriate label. 

7 At the label INVALID_COMMAND, the procedure writes an error message 
and displays the help text that lists the commands that are valid. 

8 The help text lists the commands that are valid. This text is displayed 
initially. It is also displayed whenever the user enters the FIELP command or 
any invalid command. 

9 At the conclusion of the FIELP text, the GOTO command specifies the symbol 
name PROMPT. When this procedure is first invoked, the symbol has the 
value I NIT. Thereafter, it has the value GET_COMMAND. 

10 Each valid command in the list has a corresponding entry in the option table 
and a corresponding label in the command procedure. For the commands that 
read input from the terminal, for example, EDIT, the procedure contains a 
DEFI NE command that defines the input stream as SYS$COM MAND. 

11 At the label BADFI LE, the procedure displays a message indicating that the 
file must be in the current directory. Then the procedure prompts for another 
file name. 

12 After obtaining a file name, the procedure checks that you have not specified a 
directory that is different from your current default directory. The procedure 
then uses the F$PARSE function to extract the file name. (Each command 
supplies the appropriate default file type.) Next, the procedure branches back 
to the label GET_COMMAND to get a command to process the file. 

Sample Execution for FORTUSER.COM Command Procedure 

This example illustrates how to use this command procedure as a captive 

command procedure. 

Username: CLASS30 

Password: 


OpenVMS Version 6.1 
OpenVMS FORTRAN Command Interpreter 
Enter name of file with which you would like to work. 
The commands you can enter are: 
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FILE Name of FORTRAN program in your current 

default directory. Subsequent commands 
process this file. 

EDIT Edit the program. 

COMPILE Compile the program with VAX FORTRAN. 

LINK Link the program to produce an executable image. 

RUN Run the program's executable image. 

EXECUTE Same function as COMPILE, LINK and RUN. 

DEBUG Run the program under control of the debugger. 

PRINT Queue the most recent listing file for printing. 

DONE Return to interactive command level. 

HELP Print this help message. 

Enter Ctrl/Y to restart this session 
File name: AVERAGE 
Command: COMPILE 
Command: LINK 
Command: RUN 
Command: FILE 
File name: READFILE 
Command: EDIT 

This sample execution illustrates a session in which a user named CLASS30 
logs in to the account controlled by the FORTUSER command procedure. The 
FORTUSER command procedure displays the commands the user is allowed 
to execute, as well as an instruction for restarting the session. Next, the user 
specifies the file AVERAGE, compiles, links, and runs it. Then, the user enters 
the FILE command to begin working on another file. 

C.9 LISTER.COM Command Procedure 

$ ! Procedure to accumulate programmer names and document file names. 

$ ! After all programmer names and file names are entered, they are 
$ ! sorted in alphabetic order by programmer name and printed on 
$ ! the system printer. 

$ ! 

$ SAVE_VERIFY_IMAGE = F$ENVIRONMENT ( "VERIFY_IMAGE" ) 1 

$ SAVE_VERIFY_PROCEDURE = F$VERIFY(0) 

$ ! 

$ OPEN/WRITE OUTFILE DATA.TMP ! Create output file 2 

$ ! 

$ ! Loop to obtain programmers' last names and file names, 

$ ! and write this data to DATA.TMP. 

$ ! 

$ LOOP : 3 

$ INQUIRE NAME "Programmer (press Return to quit)" 

$ IF NAME . EQS . "" THEN GOTO FINISHED 

$ INQUIRE FILE "Document file name" 

$ RECORD[0,20] :='NAME' 4 

$ RECORD [21, 20] :='FILE' 

$ WRITE OUTFILE RECORD 

$ GOTO LOOP 

$ FINISHED: 

$ CLOSE OUTFILE 

$ ! 

$ DEFINE/USER_MODE SYS$OUTPUT: NL: ! Suppress sort output 

$ SORT/KEY= (POSITION: 1, SIZE=20) DATA.TMP DOC.SRT 5 

$ ! 

$ OPEN/WRITE OUTFILE DOCUMENT . DAT 6 

$ WRITE OUTFILE "Programmer Files as of ",F$TIME() 

$ WRITE OUTFILE "" 

$ RECORD [0, 20] : ="Programmer Name" 

$ RECORD [21,20] :="File Name" 

$ WRITE OUTFILE RECORD 
$ WRITE OUTFILE "" 
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$ ! 

$ CLOSE OUTFILE 7 

$ APPEND DOC.SRT DOCUMENT . DAT 
$ PRINT DOCUMENT . DAT 
$ ! 

$ INQUIRE CLEANJJP "Delete temporary files [Y,N] " 8 

$ IF CLEANJJP THEN DELETE DATA. TMP; *, DOC . SRT; * 

$ SAVE_VERIFY_PROCEDURE = F$VERIFY (SAVE_VERIFY_PROCEDURE, SAVE_VERIFY_IMAGE) 

$ EXIT 

Notes for LISTER.COM Command Procedure 

1 LI STER.COM saves the current verification setting and turns off verification. 

2 The OPEN command creates a temporary file for writing. 

3 I NQUI RE commands prompt for a programmer name and for a file name. If a 
null line, signaled by pressing Return, is entered in response to the INQUIRE 
command prompt, the procedure assumes that no more data is to be entered 
and branches to the label FINISHED. 

4 After assigning values to the symbols NAM E and FI LE, the procedure uses 
the character string overlay format of an assignment statement to construct 
a value for the symbol RECORD. I n columns 1 to 21 of RECORD, the current 
value of NAME is written. The command interpreter pads the value of NAME 
with spaces to fill the 20-character length specified. 

Similarly, the next 20 columns of RECORD are filled with the value of FI LE. 
Then, the value of RECORD is written to the output file. 

5 After the file has been closed, the procedure sorts the output file DATA.TMP. 
The DEFI NE command directs the SORT command output to the null file NL. 
Otherwise, these statistics would be displayed on the terminal: 

The sort is performed on the first 20 columns; that is, by programmer name. 
The sorted output file has the name DOC.SRT. 

6 The procedure creates the final output file, DOCUMENT.DAT, with the OPEN 
command. The first lines written to the file are header lines, giving a title, 
the date and time of day, and headings for the columns. 

7 The procedure closes the file DOCUMENT.DAT and appends the sorted 
output file, DOC.SRT, to it. Then, the output file is queued to the system 
printer. 

8 The procedure prompts to determine whether to delete the intermediate files. 
If a true response (T, t, Y, or y) is entered at the INQUIRE command prompt, 
the files DATA.TMP and DOC.SRT are deleted. Otherwise, they are retained. 

Sample Execution for LISTER.COM Command Procedure 

$ 0LISTER 

Programmer: WATERS 

Document file name: CRYSTAL. CAV 

Programmer: JENKINS 

Document file name: MARIGOLD.DAT 

Programmer: MASON 

Document file name: SYSTEM. SRC 

Programmer: ANDERSON 

Document file name: JUNK.J 

Programmer: | Return | 

Delete temporary files [ Y, N] :y 
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The output file resulting from this execution of the procedure contains the 
following: 

Programmer Files as of 31-DEC-1994 16:18:58.79 

Programmer Name File Name 

ANDERSON JUNK.J 

JENKINS MARIGOLD.DAT 

MASON SYSTEM. SRC 

WATERS CRYSTAL. CAV 


C.10 CALC.COM Command Procedure 


Procedure to calculate expressions. If you enter an 
assignment statement, then CALC.COM evaluates the expression 
and assigns the result to the symbol you specify. In the next 
iteration, you can use either your symbol or the symbol Q to 
represent the current result. 

If you enter an expression, then CALC.COM evaluates the 
expression and assigns the result to the symbol Q. In 
the next iteration, you can use the symbol Q to represent 
the current result. 


$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ SAVE_VERIFY_IMAGE = F$ENVIRONMENT ("VERIFY_IMAGE") 

$ SAVE_VERIFY_PROCEDURE = F$VERIFY(0) 

$ START: 

ON WARNING THEN GOTO START 1 

INQUIRE STRING "Calc" 2 

IF STRING . EQS . "" THEN GOTO CLEANJJP 

IF F$LOCATE("=", STRING) .EQ. F$LENGTH (STRING) THEN GOTO EXPRESSION 


Execute if string is in the form symbol = expression 


$ STATEMENT: 


! Execute assignment statements 

F$EXTRACT(0,F$LOCATE("=", STRING) -1, STRING) ! get symbol name 
Set up q for future iterations 
= ! SL Hex = ! - ! XL Octal = !-!OL",Q) 


'STRING 
SYMBOL 
Q = 'SYMBOL' ! 

LINE = F$FAO( "Decimal 
WRITE SYS$OUTPUT LINE 
GOTO START 


Execute if string is an expression 


$ EXPRESSION: 


Q = F$INTEGER(' STRING' ) 
LINE = F$FAO( "Decimal = 
WRITE SYS$OUTPUT LINE 
GOTO START 


$ 

$ 

$ 

$ 

$ ! 

$ CLEANJJP: 

$ SAVE_VERIFY_PROCEDURE 
$ EXIT 


! SL 


Can use Q in next iteration 
Hex = ! — ! XL Octal = !-!OL",Q) 


F$VERIFY (SAVE_VERIFY_PROCEDURE, SAVE_VERIFY_IMAGE ) 


Notes for CALC.COM Command Procedure 


i The procedure establishes an error-handling condition that restarts the 
procedure. If a warning or an error of greater severity occurs, the procedure 
will branch to the beginning where it resets the ON condition. 

This technique ensures that the procedure will not exit if the user enters an 
expression incorrectly. 
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2 The INQUIRE command prompts for an arithmetic expression. The procedure 
accepts expressions in either of the following formats: 

name = expression 

expression 

If you press Return, the procedure assumes the end of a CALC session and 
exits. 

If you enter input in the format "name = expression" then the procedure 
continues executing at the label STATEMENT. Otherwise, the procedure 
branches to the label EXPRESSION. 

3 The procedure executes the assignment statement and assigns the result of 
the expression to the symbol. Then the procedure extracts the symbol name, 
and assigns the value of the symbol to Q. This allows you to use either Q or 
your symbol during the next iteration of the procedure. Next, the procedure 
displays the result and then branches back to the label START. 

4 The procedure evaluates the expression and assigns the result to the symbol 
Q. This allows you to use Q during the next iteration of the procedure. Next, 
the procedure displays the result and then branches back to the label START. 

Sample Execution for CALC.COM Command Procedure 

$ @CALC 
Calc: 2 * 30 

Decimal = 60 Hex = 0000003C Octal = 00000000074 

Calc: Q + 3 

Decimal = 63 Hex = 0000003F Octal = 00000000077 

Calc: TOTAL = Q + 4 

Decimal = 67 Hex = 00000043 Octal = 00000000103 

Calc: 5+7 

Decimal = 12 Hex = 0000000C Octal = 00000000014 

Calc : | Return | 

$ 

After each prompt from the procedure, the user enters an arithmetic expression. 
The procedure displays the results in decimal, hexadecimal, and octal. A null 
line, signaled by pressing Return on a line with no data, concludes the CALC 
session. 

C.11 BATCH.COM Command Procedure 

$ VERIFY_IMAGE = F$ENVIRONMENT ( "VERIFY_IMAGE" ) 

$ VERIFY_PROCEDURE = F$VERIFY(0) 

$ ! 

$! Turn off verification and save current settings. 

$! (This comment must appear after you turn verification 
$! off; otherwise it will appear in the batch job log file.) 

$ ! 

$! 

$! If this is being executed as a batch job, 

$! (from the SUBMIT section below) go to the EXECUTE_BATCH_JOB section 
$! Otherwise, get the information you need to prepare to execute the 
$! batch job. 

$ ! 

$ IF F$M0DE() . EQS. "BATCH" THEN GOTO EXECUTE_BATCH_JOB 1 

S! 

$ ! 

$! Prepare to submit a command (or a command procedure) as a batch job. 

$! First, determine a mnemonic process name for the batch job. Use the 
$! following rules: 
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$! 

$! 1) If the user is executing a single command, then use the verb name. 

$! Strip off any qualifiers that were included with the command. 

$! 2) If the user is executing a command procedure, then use the file name. 

$! 3) Otherwise, use BATCH. 

$! 

$ JOB_NAME = PI 2 

$ IF JOB_NAME . EQS. "" THEN JOB_NAME = "BATCH" 

$ IF F$EXTRACT (0,1, J0B_NAME) .EQS. "@" THEN J0B_NAME = F$EXTRACT (1, 999, J0B_NAME) 
$ J0B_NAME = F$EXTRACT (0, F$L0CATE ("/", J0B_NAME) , J0B_NAME) 

$ J0B_NAME = F$PARSE(JOB_NAME,,,"NAME","SYNTAX_ONLY") 

$ IF J0B_NAME .EQS. "" THEN J0B_NAME = "BATCH" 

$! 

$ ! 

$! Get the current default device and directory. 

$! 

$ ORIGDIR = F$ENVIR0NMENT( "DEFAULT") 

$ ! 

$! 

$! Concatenate the parameters to form the command string to be executed. 

$! If the user did not enter a command string, the symbol COMMAND will have 
$! a null value. 

$ ! 

$ COMMAND = PI + " " + P2 + " " + P3 + " " + P4 + " " + - 3 
P5 + " " + P6 + " " + P7 + " " + P8 

$! 

$! 

$! If the user is executing a single command and if both the command and the 
$! original directory specification are small enough to be passed as 
$! parameters to the SUBMIT command, then submit the batch job now 
$ ! 

$ IF (PI .NES. "") .AND. (F$LENGTH (COMMAND) .LE. 255) .AND. - 4 

(F$LENGTH (ORIGDIR) .LE. 255) THEN GOTO SUBMIT 

$! 

$ ! 

$! If the single command to be executed in the batch job is very large, or 
$! if you have to prompt for commands to execute in the batch job, then 
$! create a temporary command procedure to hold those commands and get the 
$! fully expanded name of the command procedure. 

$! 

$ CREATE_TEMP_FILE : 

$ ON C0NTR0L_Y THEN GOTO C0NTR0L_Y_HANDLER 5 

$ 0PEN/WRITE/ERR0R=FILE_0PEN_ERR0R TEMPFILE SYS$SCRATCH : ' J0B_NAME' . TMP 6 
$ FILESPEC = F$SEARCH ( "SYS$SCRATCH : " + J0B_NAME + ".TMP") 

$! 

$! By default, have the batch job continue if it encounters any errors. 

$ ! 

$ WRITE TEMPFILE "$ SET NOON" 

$! 

$! Either write the single large command to the file, or prompt for 
$! multiple commands and write them to the file. 

$! 

$ IF COMMAND .NES. " " THEN GOTO WRI TE_LARGE_COMMAND 

$ 

$ LOOP : 

$ READ /END_0F_FILE=CL0SE_FILE /PR0MPT="Command: " SYS$C0MMAND COMMAND 

$ IF COMMAND .EQS. "" THEN GOTO CL0SE_FILE 

$ WRITE TEMPFILE "$ ", COMMAND 

$ GOTO LOOP 

$ 

$ WRITE_LARGE_COMMAND : 

$ WRITE TEMPFILE "$ ", COMMAND 

$ 
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$ ! 

$! Finish the temporary file by defining a symbol so that you will know 
$! the name of the command procedure to delete and then close the file. 

$! Define the symbol COMMAND to mean "execute the command procedure 
$! you have just created". Then submit the batch job and execute 
$! this command procedure in the batch job. 

S! 

$ CLOSE_FILE : 7 

$ WRITE TEMPFILE "$ BATCH$DELETE_FILESPEC == " " " , FILESPEC, " " " " 

$ CLOSE TEMPFILE 
$ ON CONTROL_Y THEN EXIT 

$ COMMAND = + FILESPEC 

$ ! 

$! 

$! Submit BATCH.COM as a batch job, and pass it two parameters. 

$! PI is the command (or name of the command procedure) to execute. 

$! P2 is the directory from which to execute the command. 

S! 

$ SUBMIT: 8 

$ SUBMIT/NOTIFY/NOPRINT ' F$ENVIRONMENT ( "PROCEDURE" ) ' /NAME=' JOB_NAME' - 
/PARAMETERS= ("" COMMAND' " , " " ORIGDIR' " ) 

$ GOTO EXIT 
S! 

$! 

$! The user pressed Ctrl/Y while the temporary command procedure was open. 
$! Close the command procedure, delete it if it exists, and exit. 

$ ! 

$ CONTROL_Y_HANDLER : 9 

$ CLOSE TEMPFILE 

$ IF F$TYPE (FILESPEC) .NES. "" THEN DELETE/NOLOG 'FILESPEC' 

S WRITE SYS$OUTPUT "Ctrl/Y caused the command procedure to abort." 

$ GOTO EXIT 

$ ! 

$! 

$! The temporary command procedure could not be created. 

$! Notify the user and exit. 

$! 

$ FILE_OPEN_ERROR: 10 

$ WRITE SYS$OUTPUT "Could not create sys$scratch: ", job_name, " .tmp" 

$ WRITE SYS$OUTPUT "Please correct the situation and try again." 

$ ! 

$! 

$! Restore the verification states and exit. 

S! 

$ EXIT: 11 

$ VERIFY_PROCEDURE = F$VERIFY (VERIFY_PROCEDURE, VERIFY_IMAGE) 

$ EXIT 
$ ! 

$! 

$! BATCH.COM was invoked as a batch job. PI contains the command 
$! to execute and P2 the default directory specification. 

$! Return a status code that indicates the termination status of PI. 

$ ! 

$ EXECUTE_BATCH_JOB : 12 

$ SET NOON 

$ VERIFY_PROCEDURE = F$VERIFY (VERIFY_PROCEDURE, VERIFY_IMAGE) 

$ SET DEFAULT ' P2' 

$ 'PI' 

$ IF F$TYPE (BATCH$DELETE_FILESPEC) ,EQS. "" THEN EXIT $STATUS 

$ STATUS = $ STATUS 

$ DELETE /NOLOG ' BATCH$DELETE_FILESPEC' 

$ EXIT STATUS 
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Notes for BATCH.COM Command Procedure 

1 This IF statement tests whether BATCH.COM is executing in batch mode. 
When you invoke BATCH.COM interactively, you provide (as parameters) a 
command string or a command procedure that is to be executed as a batch 
job. If you do not supply any parameters, then BATCH .COM prompts you for 
commands, writes these commands to a file, and then executes this command 
procedure as a batch job. After BATCH.COM prepares your commands for 
execution from a batch job, it uses the SUBMIT command to submit itself 
as a batch job and execute your commands from this job. (See Note 8.) 

When you invoke BATCH .COM as a batch job, the procedure branches to the 
label EXECUTE_BATCH J OB. Note that you must specify the command or 
command procedure to execute as PI and the default directory as P2 if you 
executeBATCH.COM in batch mode. 

2 These commands prepare the batch job for execution. First, the procedure 
constructs a name for the batch job. If a command string was passed, then 
BATCH.COM uses the verb name as the job name. If a command procedure 
was passed, then BATCH .COM uses the file name. If no input was passed, 
then BATCH.COM names the job BATCH. 

3 The parameters are concatenated to form the command string to be executed. 
The command string is assigned to the symbol COMMAND. 

4 The SUBMIT command cannot pass a parameter that is greater than 255 
characters. Therefore, the procedure tests that the command string and 
directory name are less than 255 characters long. If both strings are less 
than 255 characters (and if the user did, in fact, pass a command string), 
then the procedure branches to the label SUBMIT. 

5 The procedure establishes a Ctrl/Y handler, so cleanup operations are 
performed if the user presses Ctrl/Y during this section of the command 
procedure. 

6 The procedure creates a temporary file to contain the commands to be 
executed. If the user supplies a long command string, the procedure branches 
to WRITE_LARGE_COMMAND and writes this command to the temporary 
file. Otherwise, the procedure prompts for the commands to be executed. 
Each command is written to the temporary file. 

7 Before you close the temporary file, write a symbol assignment statement to 
the file. This statement assigns the file name for the temporary file to the 
symbol BATCH $DELETE_FI LESPEC. After closing the temporary file, the 
procedure resets the default Ctrl/Y handler. Then the procedure defines the 
symbol COMMAND so that, when executed, the symbol COMMAND invokes 
the temporary command file. 

8 The procedure submits itself as a batch job, using the defined job name. 

(See Note 2.) The procedure also passes two parameters: the command 
or command procedure to be executed, and the directory from which the 
command should be executed. Then the procedure branches to the label EXIT. 
(See Note 11.) 

9 This section performs clean-up operations if the user enters Ctrl/Y while the 
temporary file is being created. 

10 This section writes an error message if the temporary file cannot be created. 

11 The procedure resets the original verification settings and then exits. 
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12 These commands are executed when BATCH.COM runs in batch mode. First, 
ON error handling is disabled and the user's default verification settings are 
set. Then the default is set to the directory indicated by P2, and the command 
or command procedure indicated by PI is executed. If a temporary file was 
created, this file is deleted. The completion status for PI is saved before 
deleting BATCH $DELETE_FI LESPEC. This completion status is returned by 
the EXIT command. 

Sample Execution for BATCH.COM Command Procedure 

$ @ BATCH RUN MYPROG 

Job RUN (queue SYS$BATCH, entry 1715) started on SYS$BATCH 

This example uses BATCH.COM to run a program from within a batch job. 

C.12 COMPILE_FILE.COM Command Procedure 

$! This command procedure compiles, links, and runs a file written in Pascal 
$! or FORTRAN. 

S! 

$ ON CONTROLJY THEN EXIT 

$! 

$ TOP: 

$ INQUIRE FILE "File to process" 

$ IF F$SEARCH (FILE) .NES. "" 1 

$ THEN 

$ FILE_TYPE = F$PARSE (FILE, ,, "TYPE") 2 ! determine file type 

$ FILE_TYPE = F$EXTRACT(1,F$LENGTH('FILE_TYPE' ) ,FILE_TYPE) ! remove period 
$! Remove type from file specification 
$ PERIOD_LOC = F$LOCATE ( " . ", FILE) 

$ FILE = F$EXTRACT (0, PERIOD_LOC, FILE) 

$ ON WARNING THEN GOTO OTHER 
$ GOTO ' FILE_TYPE' 

$ ELSE 3 

$ WRITE SYS$OUTPUT FILE, "does not exist" 

$ ENDIF 4 

S! 

$ GOTO END 

$ ! 

$! 

$! 

$ FOR: 5 

$ ON ERROR THEN GOTO PRINT 
$ FORTRAN/LIST 'FILE' 

$ GOTO LINK 

SI 

$ PAS: 

$ ON ERROR THEN GOTO PRINT 
$ PASCAL/LIST 'FILE' 

$ GOTO LINK 

$ ! 

$ OTHER: 

$ WRITE SYSSOUTPUT "Can't handle files of type . ' ' FILE_TYPE' " 

$ GOTO END 
S! 

$ LINK: 6 

$ ON ERROR THEN GOTO END 

$ WRITE SYSSOUTPUT "Successful compilation " 

S LINK 'FILE' 

S DEFINE/USER_MODE SYS$INPUT SYS$COMMAND 
$ RUN 'FILE' 

$ GOTO CLEANUP 
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$! 

$ PRINT: 7 

$ WRITE SYS$OUTPUT "Unsuccessful compilation, printing listing file 

$ PRINT 'FILE' 

$! 

$ CLEANUP: 

$ DELETE 'FILE'. OBJ; 

$ DELETE 'FILE'. LIS; 

$! 

$ END: 

$ INQUIRE/NOPUNCTUATION ANS "Process another file (Y or N) ? " 

$ IF ANS THEN GOTO TOP 

$ EXIT 

Notes for COMPILE_FILE.COM Command Procedure 

1 The IF command uses the F$SE ARCH lexical function to search the directory 
and determine if the file exists. 

2 The command block following the THEN command: 

• Uses the F$LENGTH lexical function to determine the length of the file 
type 

• Determines the file type 

• Removes the period from the file type 

• Removes the file type from the file specification to determine the file name 

• Removes the period from the file name 

• Defines an action to perform if an error occurs 

• Branches to the label defined by the symbol FILE_TYPE 

3 If the file you entered at the "File to process:" prompt does not exist in the 
directory, the command following the ELSE command executes. 

4 TheENDIF command ends the I F-TH EN -ELSE command language construct. 

5 The procedure compiles the FORTRAN program and branches to the LI NK 
label. If an error occurs during the compilation, the procedure branches to 
the PRINT label. 

6 The procedure displays that the program compiled correctly, links and runs 
the program, and branches to the CLEANUP label. The program branches to 
the END label if an error occurs. 

7 The procedure enters the listing file of the program in the default print queue. 

Sample Execution for COMPLILE_FILE.COM Command Procedure 

$ @COMPILE_FILE 

File to process: RAND. PAS 

Successful compilation 

%DELETE-I-FILDEL, WORK: [DESCH] RAND. OBJ; 1 deleted (3 blocks) 

%DELETE-I-FILDEL, WORK: [DESCH] RAND .LIS; 1 deleted (9 blocks) 

Process another file (Y or N) ? N | Return | 
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The following tables present the operating system's interpretation of terminal 
keys. 

D.1 LK201 Keyboard 

The following table describes how the operating system responds when various 
keys and control characters are pressed on an LK201 keyboard (VT200 series 
and later terminals, and workstations). The table assumes that line editing is 
enabled (the default). Characters not mentioned in the table are treated as null 
characters. 


Character 

Hex 

System Response 

Ctrl/A 

01 

Switches between overstrike and insert modes 

Ctrl/B 

02 

Recalls previous line 

Ctrl/C 

03 

Interrupts current image (image may define alternate 
Ctrl/C action) 

Ctrl/D 

04 

Moves cursor left one character 

Ctrl/E 

05 

Moves cursor to end of line 

Ctrl/F 

06 

Moves cursor right one character 

Ctrl/H 

08 

Moves cursor to beginning of line 

Ctrl/I 

09 

Horizontal tab 

Ctrl/J 

0A 

Deletes previous word 

Ctrl/M 

0D 

Line terminator 

Ctrl/O 

OF 

Suspends or resumes echoing of output 

Ctrl/Q 

11 

Resumes output (see Ctrl/S) 

Ctrl/R 

12 

Refreshes current line 

Ctrl/S 

13 

Suspends output (see Ctrl/Q) 

Ctrl/T 

14 

Displays process information (must be enabled with SET 
CONTROL =T command) 

Ctrl/U 

15 

Deletes characters from cursor to beginning of line 

Ctrl/V 

16 

Passes next character or escape sequence to the image 
without interpreting it as described in this table 

Ctrl/X 

18 

Purges type-ahead buffer; if characters are on the current 
line, deletes characters from cursor to beginning of line 

Ctrl/Y 

19 

1 nterrupts current image 

Ctrl/Z 

1A 

1 ndicates end of file 

Data keys 

- 

Enters appropriate character 
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Character 

Hex 

System Response 

<3 

- 

Deletes previous character 

Ctrl 

- 

Modifies another key 

Ctrl/[ (ESC) 

IB 

Begins escape sequence 

Ctrl/F 5 

- 

Executes answerback message 

l 

- 

Repeats current line 

FI (No Scroll) 

- 

Suspends or resumes output 

F 5 (Break) 

- 

Shuts down transmission line 

F6 (1 nterrupt) 

- 

1 nterrupts current image 

F 10 (Exit) 

- 

Terminates current image or command procedure 

F 12 (Backspace) 

08 

Moves cursor to beginning of line 

F 13 (Line Feed) 

- 

Deletes previous word 

F 14 PA) 

01 

Switches between overstrike and insert modes 


- 

Moves cursor left one character 

PFn 

- 

Can be defined (see Section 3.7) 

Return 

- 

Line terminator 

— > 

- 

Moves cursor right one character 

Tab 

- 

Horizontal tab 

t 

- 

Repeats current line 


D.2 VT100 Terminal Series 

The following table describes how the operating system responds when various 
keys and control characters are pressed on VT100 series terminals. The table 
assumes that line editing is enabled (the default). Characters not mentioned in 
the table are treated as null characters. 


Character 

Hex 

System Response 

Ctrl/A 

01 

Switches between overstrike and insert modes 

Ctrl/B 

02 

Recalls previous line 

Ctrl/C 

03 

Interrupts current image (image may define alternate 
Ctrl/C action) 

Ctrl/D 

04 

Moves cursor left one character 

Ctrl/E 

05 

Moves cursor to end of line 

Ctrl/F 

06 

Moves cursor right one character 

Ctrl/H 

08 

Moves cursor to beginning of line 

Ctrl/I 

09 

Horizontal tab 

Ctrl/J 

0A 

Deletes previous word 

Ctrl/M 

0D 

Line terminator 

Ctrl/O 

OF 

Suspends or resumes echoing of output 

Ctrl/Q 

11 

Resumes output (see Ctrl/S) 

Ctrl/R 

12 

Refreshes current line 

Ctrl/S 

13 

Suspends output (see Ctrl/Q) 


D-2 


Terminal Keys 
D.2 VT100 Terminal Series 


Character 

Hex 

System Response 

Ctrl/T 

14 

Displays process information 

Ctrl/U 

15 

Deletes characters from cursor to beginning of line 

Ctrl/V 

16 

Passes next character or escape sequence to the image 
without interpreting it as described in this table 

Ctrl/X 

18 

Purges type-ahead buffer; if characters are on the 
current line, deletes characters from cursor to beginning 
of 1 i ne 

Ctrl/Y 

19 

1 nterrupts current image 

Ctrl/Z 

1A 

1 ndi cates end of file 

Data keys 

- 

Enters appropriate character 

Backspace (~H) 

08 

Moves cursor to beginning of line 

Break 

- 

Shuts down transmission line 

Ctrl 

- 

Modifies another key 

Ctrl/Break 

- 

Executes answerback message 

Delete 

- 

Deletes previous character 


- 

Repeats current line 

Esc 

IB 

Begins escape sequence 

«- 

- 

Moves cursor left one character 

Line Feed 

- 

Deletes previous word 

No Scroll 

- 

Suspends or resumes output 

PFn 

- 

Can be defined (see Section 3.7) 

Return 

- 

Line terminator 

— > 

- 

Moves cursor right one character 

Tab 

- 

Horizontal tab 

t 

- 

Repeats current line 
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access control entry (ACE) 

An entry in an access control list. Access control entries may specify identifiers 
and the access rights to be granted or denied to the holders of the identifiers, 
default protection for directories, or security alarm details. 

access control string 

A series of 0 to 42 characters that contains login information to be sent to a 
remote node. On OpenVMS systems, an access control string usually consists of a 
user name, spaces or tabs, and a password. 

account 

Every user must have an account to use the system. The account is identified by 
the user's user name. Different accounts allow different levels of service from the 
system (for example, the privileges users hold, the times during which they can 
log in, and so on). 

American Standard Code for Information Interchange (ASCII) 

A set of 8-bit binary numbers representing the alphabet, punctuation, numerals, 
and other special symbols used in text representation and communications 
protocol . 

ASCII 

See American Standard Code for Information Interchange. 

assignment statement 

I n DCL, the association of a symbol name with a character string or numeric 
value. Symbols can define synonyms for system commands or can be used as 
variables in command procedures. 

batch job 

A program that is scheduled and executed under the control of the batch 
processing subsystem. Control input for a batch job comes from a command 
procedure stored on disk, and output is directed to a disk file. 

break-in attempt 

An effort made by an unauthorized source to gain access to the system. Because 
the first system access is achieved through logging in, break-in attempts 
primarily refer to attempts to log in illegally. These attempts focus on supplying 
passwords for users known to have accounts on the system through informed 
guesses or other trial-and-error methods. 
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buffer 


An internal memory area used for temporary storage of data records during input 
or output operations. 

captive account 

A type of OpenVMS account that limits the activities of the user. Typically, the 
user is restricted to using certain command procedures and commands. For 
example, the user may not be allowed to use the Ctrl/Y key sequence. This type 
of account is synonymous with a turnkey or a tied account. 

central processing unit (CPU) 

The hardware that handles all calculating and routing of input and output as 
well as executing programs. I n short, the CPU is the part of the computer that 
actually computes. 

character string 

A contiguous set of bytes. A character string is identified by two attributes: an 
address and a length. Its address is the address of the byte containing the first 
character of the string; subsequent characters are stored on bytes on increasing 
addresses. The length is the number of characters in the string. 

close 

To terminate all operations on a file. 

collating sequence 

An order assigned to the characters of a character set (for example, ASCII, 
Multinational, or EBCDIC) used for sequencing purposes. 

command 

In DIGITAL Command Language (DCL), an instruction, generally an English 
word, entered by the user at a terminal or included in a command procedure. A 
command requests the software monitoring a terminal or reading a command 
procedure to perform some well-defined activity. For example, entering the COPY 
command requests the system to copy the contents of one file into another file. 

command image 

A program associated with and invoked by a DCL command. 

command interpreter 

A procedure-based system code that executes in supervisor mode in the context of 
a process to receive, to check the syntax of, and to parse commands entered by 
the user at a terminal or submitted in a command file. 

command level 

Input stream for the command interpreter. The initial input stream is always 
command level 0. An interactive command procedure begins executing at 
command level 1. A batch job command procedure begins executing at command 
level 0. You can use the execute procedure (@) command or the CALL command 
in a command procedure to create up to 32 nested command levels. 
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command parameter 

The positional operand of a command delimited by spaces, such as a file 
specification, an option, or a constant. 

command procedure 

A file containing commands and data that the command interpreter can accept 
instead of the users entering the commands individually at a terminal. Thus, 
command procedures provide a means of automatically passing commands to the 
operating system. In addition, they permit users to employ such programming 
techniques as loops, counters, labels, and symbol substitution to set up elaborate 
command sequences that can be altered through user interaction. Command 
procedures can also be submitted to the system for processing as batch jobs. 

command string 

A line (or set of continued lines) containing a command and, optionally, 
information modifying the command. A command string consists of a command, 
its qualifiers, its parameters (file specifications, for example), and their qualifiers. 
A command string is normally terminated by pressing the Return key. 

concatenate 

The act of linking files together in a series. 

CPU 

See central processing unit. 

cursor 

An indicator used on a video terminal to point to the screen position where the 
next character will appear. 

data 

A general term referring to any representation of facts, concepts, or instructions 
in a form suitable for communication, interpretation, or processing. 

DCL (DIGITAL Command Language) 

A command interpreter in an OpenVMS system. It provides a means of 
communication between the user and the operating system. 

DECnet/OSI 

Family of Digital hardware and software products that implement the Digital 
Network Architecture (DNA) Phase V, which integrates OSI and DNA protocols; 
compliant with OSI and compatible with DECnet Phase IV and TCP/I P. 

default 

A value or operation that is automatically included in a command, unless the 
user specifies otherwise. In most cases, default settings will be what is "normal" 
or "expected." 

default directory 

The directory that the OpenVMS operating system assumes when a directory 
specification has not been supplied by the user. 
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default disk 

The disk from which the system reads and to which the system writes; by default, 
all files that you create. The default is used whenever a file specification in a 
command does not explicitly name a device. 

delimiter 

A character that separates, terminates, or organizes elements of a character 
string, statement, or program. 

detached process 

A process that has no owner. The job controller creates a detached process when 
a user logs in to the system. It also creates a detached process each time it 
initiates a batch job or services a request for a logical link connect. Because the 
job controller does not own the processes it creates, these processes are referred 
to as detached. The DCL command RUN/UIC and the Create Process system 
service (specifying a UIC) allow a suitably privileged process to request creation 
of a detached process. 

device 

The general name for any peripheral connected to the processor that is capable 
of receiving, storing, or transmitting data. Card readers, line printers, and 
terminals are examples of record-oriented devices. Magnetic tape devices and 
disk devices are examples of mass storage devices. Terminal line interfaces and 
inter processor links are examples of communications devices. Devices are not 
necessarily hardware. 

device name 

The field in a file specification that identifies the device unit on which a file is 
stored. Device names also include the mnemonics that identify an I/O peripheral 
device in a data transfer request. A device name consists of a mnemonic followed 
by a controller identification letter (if applicable), followed by a unit number (if 
applicable), and ends with a colon. 

DIGITAL Command Language (DCL) 

See DCL (DIGITAL Command Language. 

directory 

A file that briefly catalogs a set of files stored on disk or tape. The directory 
includes the name, type, and version number of each file in the set, as well as a 
unique number that identifies the file's actual location and points to a list of its 
attributes. See also subdirectory. 

disk 

High-speed, random-access devices. There are several kinds of disks. Floppy 
disks are small, flexible disks. Hard disks are either fixed in place or removable. 
Removable disk types include a single hard disk enclosed in a protective case and 
a stacked set of disks enclosed in a protective case. 

echo 

A terminal-handling characteristic in which the characters typed by the user 
from the terminal keyboard are also displayed on the screen or printer. 
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editor 

A program used to create or modify text in a computer file. 

equivalence string 

The string associated with a logical name in a logical name table. An equivalence 
string can be, for example, a device name, another logical name, or a logical name 
concatenated with a portion of a file specification. 

error message 

A message sent by the system when some action you have requested fails. Each 
error message identifies the particular part of the operating system that detected 
the error. Most error messages result from typing mistakes or mistakes in 
syntax. Often, you can correct the error by retyping the command correctly. 

executable image 

An image that can be run in a process. When run, an executable image is read 
from a file for execution in a process. 

expression 

Any combination of variables, constants, or both, with operators that the 
computer can evaluate to produce a result. 

field 

A set of contiguous bytes in a logical record. 

file 

A set of data elements arranged in a structure significant to the user. A file is 
any named, stored program or data, or both, to which the system has access. 
Access can be of two types: read-only, meaning the file is not to be altered, and 
read/write, meaning the contents of the file can be altered. See also volume. 

file name 

The field containing a 1- to 39-character name for a file that precedes a file type 
in a file specification. 

file specification 

A unique name for a file on mass storage media. It identifies the node, the device, 
the directory name, the file name, the file type, and the version number under 
which a file is stored. 

file type 

The field in a file specification that consists of a period followed by a 0- to 
39-character identification. By convention, this field identifies a generic class of 
files that have the same use or characteristics, such as compiler and assembler 
listing files, binary object files, and so on. 

folder 

A subdivision of a file in which you can store mail messages. 

foreign command 

A symbol that executes an image whose name is not recognized by the command 
interpreter as a DCL command. 
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foreign file specification 

A file whose specification does not conform to OpenVMS syntax. 

form feed 

The movement of the cursor position to the start of a new page. 

full name 

Complete specification of a name in the DECdns namespace, including all parent 
directories in the path from the root directory to the object, directory, or soft link 
being named; can also include a namespace name, but not necessary when only 
one namespace exists in a network. 

function keys 

Keyboard keys that send special signals to the operating system. Function keys 
are referred to as Fn, where n is the number associated with that key. For 
example, by pressing F9 in Mail you are telling the system you want to forward a 
message. 

generic device name 

A device name that identifies the type of device but not a particular unit; a device 
name in which the specific controller or unit number is omitted. 

global symbol 

(1) A symbol defined in a module of a program that is potentially available 
for reference by another module. The linker resolves (matches references with 
definitions) global symbols. Contrast with local symbol. 

(2) A command language symbol accessible at all command levels. 

hardware device 

The physical computer equipment, including such mechanical devices as the line 
printer, the terminals, the mass storage devices, and so forth. 

hardcopy terminal 

Terminals that print output on paper. See also terminal. 

help file 

A text file in a format suitable for use with the FI ELP command. Fielp files can 
provide up to nine levels of search. 

hierarchical directory structure 

A structure of directories that has several levels arranged in a treelike structure, 
based on a one-to-many relationship. 

identifier 

An alphanumeric string representing a user or group of users recorded in the 
rights database and used by the system in checking access requests. There are 
four types of identifiers: environmental, facility, general, and user identification 
code (UIC). 


Glossary-6 


image 

The procedures and data bound together by the linker to form an executable 
program. This executable program is executed by the process. There are three 
types of images: executable, shareable, and system. 

indexed sequential file 

A record file in which each record has one or more data keys embedded in it. 
Records in the file are individually accessible by specifying a key associated with 
the record. 

input file 

A file containing data to be transferred into the computer. 

Often input and output files are confused. DCL usually prompts for these files, 
but most system utilities require you to identify your input and output files by 
position in a command line. Be sure of the syntax for the command you are 
using. 

input stream 

The source of commands and date— the user's terminal, the batch stream, or a 
command procedure. 

interactive mode 

The mode of communication with the operating system in which you enter a 
command, and the system executes it and responds. One command has to finish 
executing before you can enter another. 

interactive utility 

A computer program, invoked with a DCL command, that provides a special 
environment from which you can perform a specific set of tasks. You work 
interactively with these utilities by entering subcommands and other information 
in response to the utility's prompt. 

iterative translation 

The repetitive translation of a logical name that occurs when a logical name's 
definition includes another logical name. 

job 

The accounting unit equivalent to a process and its subprocesses, if any, and all 
subprocesses that they create. J obs are classified as batch and interactive. For 
example, the job controller creates an interactive job to handle a user's requests 
when the user logs in to the system, and it creates a batch job when the symbiont 
manager passes a command input file to it. 

job tree 

A hierarchy of all processes and subprocesses, with the main process at the top. 

key 

(1) In indexed files, a character string, a packed decimal number, a 2- or 4-byte 
unsigned binary number, or a 2- or 4-byte signed integer within each data record 
in an indexed file. The user defines the length and location within the records; 
OpenVMS Record Management Services (RMS) uses the key to build an index. 
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(2) I n relative files, the relative record number of each data record in a data file; 
OpenVMS Record Management Services (RMS) uses the relative record numbers 
to identify and access data records in a relative file in random access mode. 

(3) In the Sort/Merge utility, the data field in a record that contains the 
information by which the user wants to sort the records. 

keyboard 

An input device that can be operated similarly to a typewriter. 

keypad 

The small set of keys next to the main keyboard on a terminal. 

keyword 

A word reserved for use in certain specified syntax formats, usually in a command 
string or a statement. 

lexical function 

A command language construct that the DIGITAL Command Language (DCL) 
command interpreter evaluates and substitutes before it parses a command 
string. Lexical functions return information about the current process (the user 
identification code (UIC) or default directory, for example) and about character 
strings (their length or the location of substrings, for example). 

line editor 

A program that allows you to make additions and deletions to a file line by line. 

line printer 

An output device that prints files one line at a time. It is used for printing large 
amounts of output that would otherwise tie up a slower device. Almost every 
system has a device designated as the line printer. I n some cases, the "line 
printer" is actually a high-speed terminal. 

local node 

The network node at which the user is physically located. 

local symbol 

(1) A symbol meaningful only to the module that defines it. Symbols not 
identified to a language processor as global symbols are considered to be local 
symbols. A language processor resolves (matches references with definitions) 
local symbols. They are not known to the linker and cannot be made available to 
another object module. They can, however, be passed through the linker to the 
debugger. Contrast with global symbol. 

(2) A command language symbol name that is accessible only at the current 
command level and subsequently invoked levels. It is deleted when the command 
level at which it is defined exits. 

logging in 

The identification of a user to the system. When users log in, they type a user 
name and password in response to prompts from the system. If the user name 
and the password match an account on the system, the user is allowed access to 
the system. 
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logging out 

The process of entering the DIGITAL Command Language (DCL) command 
LOGOUT, which informs the operating system that the user has finished using a 
particular terminal. 

logical device name 

A character string that equates a somewhat cryptic device name to a short, 
meaningful name. 

logical expression 

An expression that has a true or false value. 

logical name 

A user-specified name for any portion or all of a file specification. For example, 
the logical name INPUT can be assigned to a terminal device from which a 
program reads data entered by a user. Logical name assignments are maintained 
in logical name tables for each process, each group, and the system. Logical 
names can be assigned translation attributes, such as terminal and concealed. 

logical name table 

A table that contains a set of logical names and their equivalence strings for a 
particular process, a particular group, or the system. 

login class 

User's method of logging into the system. System managers can control system 
access based on the login class: local, dialup, remote, batch, or network. 

login command procedure 

A command procedure that is automatically executed at login and at the 
beginning of a batch job. 

login directory 

The default directory established by LOGINOUT when a when a user logs in. 

magnetic tape 

A medium on which data can be stored and accessed. 

mass storage device 

An input/output device on which data and other types of files are stored while 
they are not being used. Typical mass storage devices include disks, magnetic 
tapes, and floppy disks. 

memory 

A series of physical locations into which data or instructions can be placed in the 
form of binary words. Each location in memory can be addressed and its contents 
can be altered. Memory should not be confused with mass storage devices. 

network 

A collection of interconnected, individual computer systems. 
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node 

(1) An individual computer system in a network that can communicate with other 
computer systems in the network. 

(2) On OpenVMS VAX systems, a VAXBI interface— such as a central processing 
unit, controller, or memory subsystem— that occupies one of 16 logical locations 
on a VAXBI bus. 

(3) On OpenVMS VAX systems, a VAX processor or HSC that is recognized by 
system communications services (SCS) software. 

node specification 

The first field in a file specification. This field identifies the location of a computer 
system in a network. 

null value 

A string with no characters that is represented in a command procedure by two 
quotation marks ( " "). 

numeric expression 

A mathematical statement consisting of a collection of operands connected by 
arithmetic operators. 

object 

A passive repository of information to which the system controls access. Access to 
an object implies access to the information it contains. 

open 

The act of preparing a data set or file for processing. 

open account 

An account that does not require a password. 

operand 

The part of an expression that contains a value. Operands are acted on by 
operators during expression evaluation to produce a result. 

operating system 

An integrated collection of programs that controls the execution of computer 
programs and performs system functions. 

operator 

The part of an expression that tells the computer how to manipulate the 
operands. For example, the plus sign (+) is an operator that tells the computer to 
perform addition. 

output file 

A file that contains the results of a processing operation; for example, a file that 
has been sorted or edited. 
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parameter 

(1) A value passed to a command procedure equated to a symbol ranging from PI 
through P8. See also command parameter. 

(2) An entry in the volatile or permanent database for a network management 
component. 

parsing 

(1) Breaking a command string into its elements to interpret it. 

(2) I nterpreting a file specification, as is done by OpenVMS Record Management 
Services (RMS). 

password 

A character string that users provide at login time to validate their identities 
and as a form of proof of their authorization to access their accounts. There are 
two kinds of passwords— system passwords and user passwords. User passwords 
include both primary and secondary passwords. 

physical device name 

A character string that uniquely identifies a physical device (such as a storage 
disk or a terminal) to the system. 

primary password 

A type of user password that is the first user password requested from the user. 
Systems may optionally require a secondary password as well. The primary 
password must be the password that is associated with the user name that is 
supplied with it. 

print form 

A set of attributes that defines page set up and stock for printing. 

print queue 

A list of files waiting to be printed. 

priority 

A rank assigned to a process to determine its precedence in obtaining system 
resources when the process is running. 

private volume 

A volume that has been allocated by a process for its own exclusive use. 

process 

The basic entity scheduled by the system software. A process provides the context 
in which an image executes, and consists of an address space and both hardware 
and software context. 

program 

A series of instructions aimed at a particular result. Programming languages are 
a means of describing procedures so that they can be performed by a computer. 
See also image. 
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program stub 

A temporary section of code that is used during the testing phase of writing 
command procedures. A program stub usually outputs a message stating the 
procedure it is replacing. 

prompt 

A character string appearing on a terminal screen indicating that the user must 
provide input. 

protected object 

An object containing shareable information to which the system controls access. 
See also object. 

protection code 

A series of letters that specify what access different categories of system users 
can have to a file or other protected object and what they can do to it when they 
access it. 

proxy login 

A type of login that permits a user from a remote node to effectively log in to a 
local node as if the user owned an account on the local node. However, the user 
does not specify a password in the access control string. The remote user may 
own the account or share the account with other users. 

qualifier 

A portion of a command string that modifies a command verb or command 
parameter by selecting one of several options. A qualifier, if present, follows 
the command verb or parameter to which it applies and is in the format 
/qualifier[=option]. For example, in the command string "PRINT filename 
/COPI ES=3," the COPI ES qualifier indicates that the user wants three copies of a 
given file printed. 

queue 

(1) A line of jobs to be processed; for example, a batch job queue or a printer job 
queue. Processing occurs primarily in first-in/first-out (FIFO) order, but does 
reflect the priority of the process that submitted the job. See also print queue. 

(2) To make an entry in a list or table, often by using the I NSQUE instruction. 

random access 

A method for retrieving or writing data in which the location of the data to be 
retrieved or written is not dependent on the location of previously retrieved or 
written data. Random access refers to memory or mass storage devices on which 
all information is equally accessible. 

read 

The act or capability of an image to accept data. For example, when a TYPE 
command is issued, the system reads the designated file from disk and writes it 
to the terminal. See also write. 
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record file address (RFA) 

The unique address of a record in a file. The RFA allows previously accessed 
records to be accessed randomly at a subsequent time. This access occurs 
regardless of the file organization. 

Record Management Services (RMS) 

See RMS. 

record-oriented device 

A device such as a terminal, line printer, or card reader. A record-oriented 
device's physical record is the largest unit of data that a program can access in 
one I/O operation. 

record sorting 

A sorting process in which records are kept intact and an output file consisting of 
complete records is produced. 

relative file organization 

The arrangement of records in a file in which each record occupies a cell of 
equal length within a bucket. Each cell is assigned a successive number, which 
represents its position relative to the beginning of the file. 

remote node 

Any node in a network, other than the node that you are currently logged in to. 

restricted account 

A type of OpenVMS account with a secure login procedure. The user is not 
allowed to use the Ctrl/Y key sequence during the system or process login 
command procedure. Control may be turned over to the user following execution 
of the login command procedures. 

reverse video 

A feature of a video terminal that reverses the default video contrast. If the 
default display is black figures on a white background, reverse video displays 
white figures on a black background. 

RMS 

A set of operating system procedures that is called by programs to process files 
and records within files. RMS allows programs to issue GET and PUT requests 
at the record level (record I/O) as well as read and write blocks (block I/O). RMS 
is an integral part of the system software; its procedures run in executive mode. 

scrolling 

A feature of a video terminal that allows the display of more than one screen of 
text by vertical movement. For example, when the TYPE command is entered, 
new output appears at the bottom of the screen as the oldest output disappears 
off the top. 
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secondary password 

A user password that may be required at login time immediately after the 
primary password has been submitted correctly. Primary and secondary 
passwords can be known by separate users to ensure that more than one user is 
present at the login. A less common use is to require a secondary password as a 
means of increasing the password length so that the total number of combinations 
of characters makes password guessing more time-consuming. 

secure terminal server 

OpenVMS software designed to ensure that users can log in only to terminals 
that are already logged out. When the user presses the Break key on a terminal, 
the secure terminal server (if enabled) responds by first disconnecting any 
logged-in process and then initiating a login. If no process is logged in at the 
terminal, the login can proceed immediately. 

sequential access mode 

The retrieval or storage of records in which a program reads or writes records 
one after the other in the order in which they appear, starting and ending at any 
arbitrary point in the file. 

sequential file organization 

A file organization in which records appear in the order in which they were 
originally written. The records can be fixed or variable length. Records can be 
accessed sequentially or randomly by record address. Fixed length records can 
also be accessed randomly by relative record number. 

software 

The collection of images, procedures, rules, and documentation associated with 
the operation of a particular computer system. For example, the operating 
system is software. 

specification file 

A command file used in the Sort/Merge utility to specify the commands and 
qualifiers needed to complete a sort operation. 

string 

A connected sequence of characters. When a text editor searches for a word or 
phrase in a text file, it is looking for a string. The character sequence that forms 
a command is often called a command string. 

subdirectory 

A directory file, cataloged in a higher level directory, that lists additional files 
belonging to the owner of the directory. 

subprocess 

A subsidiary process created by another process. The process that creates a 
subprocess is its owner. A process and its subprocesses share a pool of quotas and 
limits. When an owner process is removed from the system, all its subprocesses 
(and their subprocesses) are also removed. 

subroutine 

A subsidiary routine that executes when called by another program. A subroutine 
is often called repeatedly until a certain condition is met. 
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symbol 

An entity that, when defined, represents a particular function or entity (for 
example, a command string, directory name, or file name) in a particular context. 

symbol scope 

The set of command procedure levels from within which the symbol can be 
accessed. 

syntax 

The particular form of a command, including the spelling and the order of 
qualifiers and parameters. M isspelled words are the most common syntax errors. 

system manager 

The person who makes resources available to users and sets up restrictions 
governing the use of such resources. 

system password 

A password required by a terminal before login can be initiated. 

terminal 

The general name for a peripheral device that has a keyboard and a video screen 
or printer. Under program control, a terminal enables users to type commands 
and data from the keyboard and receive messages on the video screen or printer. 
Examples of terminals are the LA36 DECwriter hardcopy terminal, the VT100 
video display terminal, and the VT240 series video terminal. 

timeout 

The expiration of the time limit during which a device is to complete an I/O 
transfer. 

time-stamp 

A text string that fully specifies a data and time. For example, ll-DEC-1994 
17:13:21. 

UAF (user authorization file) 

The file that holds details of each account on the system. The UAF contains the 
user name, password, user identification code (UIC), quotas, limits, and privileges 
assigned to each account. 

UFD (user file directory) 

A file that briefly catalogs a set of files stored on disk or tape. The UFD includes 
the name, type, and version number of each file in the set. It also contains a 
unique number that identifies that file's actual location and points to a list of its 
file attributes. See also directory. 

UIC (user identification code) 

The pair of numbers assigned to users, files, global sections, command event 
flag clusters, and mailboxes. The UIC specifies the type of access (read, write, 
or read/write, and in the case of files, execute, delete, or both) available to the 
owner, group, world, and system. 
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user authorization file (UAF) 

See UAF (user authorization file). 

user password 

A password that is associated with a user. This password must be correctly 
supplied when the user attempts to log in so that the user is approved for access 
to the system. The two types of user passwords are primary and secondary; the 
terms also represent the sequence in which they are entered. 

utility 

A program that provides a set of related general-purpose functions, such as a 
program development utility (an editor, a linker), a file management utility (file 
copy or file format translation program), or an operations management utility 
(disk quotas, diagnostic program). 

version number 

The numeric component of a file specification. When a file is edited, its version 
number is increased by one. 

video terminal 

A terminal with a video screen for accepting output. See also terminal. 

volume 

A mass storage media such as a disk pack or reel of magnetic tape. The volume 
is the largest logical unit of the file structure. 

volume set 

The file-structured collection of data residing on one or more mass storage media. 

wildcard character 

A nonalphanumeric character such as an asterisk (*) or percent sign (%) that is 
used within, or in place of, a file name, a file type, a directory name, or a version 
number in a file specification to indicate "all" for the given field. 

write 

The act or capability of an image to send data. For example, when a PRI NT 
command is issued, the specified file is read from wherever it is stored and is 
written to the printer. See also read. 
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string overlay syntax, 14-10 
syntax, 14-2 

usage of equal sign ( =) in, 14-6 
Asterisk (* ) 

See also Percent sign (%) 
as EDT prompt, 9-2 
as wildcard character 

as a multiplier, 14-12 

in directory specifications, 4-7 

in Help, 2-18 

in symbol definitions, 14-3 

in LHC format directory specifications, 5-8 

rules for using, 4-7 

using with F$DEVICE lexical function, 

16-8 

with EVE file names, 8-29, 8-40 
At sign ( @) 

executing procedures with, 15-2, 15-3 
using with a distribution list in Mail, 6-5, 6-6 
ATTACH command, 17-5 
in EVE, 8-43 

restriction on using, 8-43 
Attributes 

EVE global, A-28 

listed by startup file in EVE, A-30 

saving in EVE, A- 11 

in command files, A-15, A-33 
in section files, A- 14, A-29 
system defaults, A- 17 
Audit events 

See Security-auditing events 
Audit log files 

See also Security audit log files 
Auditing 

See Security auditing 
Automatically generated passwords, 2-11 

B 

Backspace key, 3-14,3-15 
Batch jobs 

affected by shift restrictions, 2-9 
authorization, 2-8 

deleting (stopping) after submission, 17-15 
job number of, 17-9 


Batch jobs (cont'd) 
log files, 17-11 
output, 17-11 

passing parameters to, 15-10,15-11 
providing input to, 17-10 
restarting, 15-56, 17-16 
specifying queues, 17-14 
stopping, 17-15 
submitting, 17-9 

command procedures, 1-3, 17-8 
program as, 1-3 

submitting sort operations as, 11-7 
synchronizing multiple procedures, 17-16 
uses of, 17-8 

using with command procedures, 15-2 
Batch logins, 2-8 
Batch mode 
definition, 1-3 

BATCH $RE START global symbol, 15-40, 15-56 
BATCH.COM command procedure, C-23 
Sample execution, C-27 
Bell character, 2-4, 2-7 
Bit-position in symbols, 14-14 
Bold video display 
in EVE, 8-19 

with FIND SELECTED command in EVE, 
8-25 

with the SELECT command in EVE, 8-21 
BOTTOM command 

moving the EVE cursor with, 8-8 
BOX COPY command 
in EVE, 8-20 
BOX CUT command 
in EVE, 8-20, 8-21 
BOX CUT INSERT command 
in EVE, 8-20 

BOX CUT OVERSTRIKE command 
in EVE, 8-20 
Box editing 
in EVE, 8-19 
BOX PASTE command 
in EVE, 8-20 

BOX PASTE INSERT command 
in EVE, 8-20 

BOX PASTE OVERSTRIKE command 
in EVE, 8-20 
BOX SELECT command 
in EVE, 8-20 
Break-in attempts, 2-10 
auditing, 18-8 
detection, 2-10 
evasion, 2-10 
.BRN files 

in DSR, 10-7 
BUFFER command 

changing EVE buffers, 8-40 
creating new EVE buffers with, 8-40 
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BUFFER command (cont'd) 

displaying contents of EVE Messages buffers, 
8-40 

for EVE buffer manipulation, 8-36 
putting specific EVE buffers into current 
window, 8-40 

writing EVE buffers to files, 8-41 
Buffer List buffer 

using REMOVE command in EVE, 8-37 
using SELECT command in EVE, 8-37 
Buffer-change journal i ng 
in EVE, 8-30 to 8-32 
Buffers 

deleting in EVE, 8-39 
editing multiple buffers in EVE, 8-40 
editing two buffers with two files in EVE, 8-43 
in EDT, 9-2 

in EVE, 8-4, 8-7, 8-39, A- 11 
recall DCL command, 3-11 
Built-in commands, 1-3 
See also Commands 
See also DCL Commands 
interrupting, 3-15 

c 

CALC.COM command procedure, C-22 
Sample execution, C-23 
CALL command, 15-3, 15-42 to 15-45 
CAPITALIZE WORD command 
formatting EVE text with, 8-34 
Captive accounts 
See also Accounts 
definition, 2-5 
Case sensitivity 

in DCL command line, 3-1 
of search strings in EVE, 8-23 
with REPLACE command in EVE, 8-26 
CENTER LINE command 

formatting EVE text with, 8-34 
CHANGE command 
in EDT, 9-6 

CHANGE DIRECTION command 
moving the EVE cursor with, 8-8 
CHANGE MODE command 
in EVE, 8-11 
Character data 

See also Character strings 
alphanumeric, 14-7 
expressions, 14-8 
non printable, 14-7 
special, 14-7 
Character sets 
ASCII, B-l 

DEC Multinational, B-2 
National, 11-7, 11-16 


Character strings, 14-6 

as parameter values in command strings, 15-9 
comparing, 14-8 
concatenation, 14-8 

converting using lexical functions, 16-14 
creating, 14-7 

determining presence using lexical functions, 
16-10 

evaluation of, 14-19 
expression, 14-7 

extracting using lexical functions, 16-11 
multiple string values in expressions, 14-8 
passing to command procedure, 15-9 
reducing, 14-8 

substring replacement in, 14-10 
symbol substitution in, 14-23 
used as symbols, 14-1 
values stored in, 14-6 
with lexical functions, 16-10 
$CHOICES$ buffer 

with EVE journal files, 8-33 
with input files in EVE, 8-30 
CLOSE command, 15-21, 15-23, 15-28 
Code generated for saving attributes, A- 16 
Collating sequences, 11-6 
ASCII, 11-6 
EBCDIC, 11-6 
Multinational, 11-7 

National character set (NCS), 11-7, 11-16 
Combination time 

See also Absolute time 
See also Delta time 
rules for entering, 3-10 
syntax, 3-10 
Comma ( , ) 

using in literal strings, 15-25 
Command files 
DECTPU, A-8 
in EVE, A-l, A- 33 

saving EVE attributes in, A- 15, A-31, A-33 
Command images 
See also Programs 
Command input scanning 
definition, 14-26 

Command interpreters, 14-26 to 14-29 
table of commands, 15-16 
Command levels 
nesting, 15-3 
Command lines 

continuation over multiple lines, 3-6, 14-3 

editing, 3-13 to 3-16 

in EDT, 9-2 

in Mail, 6-2 

in Phone, 7-2 

parts of, 1-4 

recalling, 3-11, 3-12 

syntax, 1-4 
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Command parsing 
definition, 14-26 
Command procedures, 1-8 
adding loops to, 15-65 
assigning conditionals in, 15-65 
assigning values to variables in, 15-64 
BATCH.COM, C-23 
CALC.COM, C-22 
changing command levels, 15-3 
cleanup, 15-69 
comments in, 15-7 
COMPILE_FILE.COM, C-27 
conditionals in, 15-62 
CONVERT.COM, C-2 
creating global symbol in, 15-17 
data line in, 15-8 
debugging, 15-68 
definition, 15-1 
deleting errors in, 15-51 
designing, 15-62 
DIR.COM, C-9 

directing output to terminal, 15-14 
disabling verification settings lexical functions, 

16- 3 

EDITALL.COM, C-14 
error handling in, 15-51, 15-53 
based on severity level, 15-54 
testing severity levels, 15-52 
using ON command with, 15-53 
executing interactively, 15-2 
executing on remote nodes, 15-5 
exiting, 15-6 
file I/O, 15-21 
format, 15-7 
FORTUSER.COM, C-17 
GETPARMS.COM, C-12 
I/O errors in, 15-32 
in Sort/Merge utility, 11-8 
input, 15-8 
input from file, 15-13 
input from terminal, 15-12 
interrupting, 15-7 
interrupting using Ctrl/Y, 15-58 
invoking, 15-3 
iteration in, 15-62 

label handling with GOTO command, 15-39 
LISTER.COM, C-20 

LOGIN.COM, 1-7, 1-8, 15-70, 15-72, 17-10, 

17- 12 

MAILEDIT.COM, C-16 
nested, 15-3, 15-10 

passing parameters to, 15-10 
overriding error handling, 15-55 
passing character string to, 15-9 
passing data to, 15-8 
passing parameters to, 14-21, 15-9 
passing symbols to, 15-9 
personal login, 15-70 


Command procedures (cont'd) 

REMINDER.COM, C-6 
returning status value in, 15-54 
submitting as batch jobs, 1-3 
SYLOGIN.COM, 17-8 
symbol substitutions, 14-27 
SYS.COM, C-ll 
system defined login, 15-70 
tape restriction, 15-3 
testing, 15-66 
used as qualifiers, 15-5 
using access control strings in, 18-5 
using program stubs in, 15-68 
variables in, 15-62 
writing file from, 15-23 
Command processing 

expression evaluation phase, 14-27 
input scanning phase, 14-26 
parsing foreign commands, 14-4 
parsing phase, 14-26 
Command qualifiers, 3-7 
Command symbols 

invoking EVE with, 8-6 
Command values 
date formats, 3-8 
time formats, 3-8 
Commands, 1-1 

See also DCL commands 

abbreviating in command procedures, 3-5 

built-in, 1-3 

canceling, 3-4 

controlling execution in command procedures, 
15-33 

entering in EDT, 9-2 
entering in Mail, 6-1 
entering in Phone, 7-2 
executing blocks of in command procedures, 
15-35 
types, 1-3 
Comments 

in a command procedure, 15-7 
in distribution lists, 6-5 
in Sort specification files, 11-12 
use of exclamation point ( !) with, 6-5, 11-12, 
15-7 

COMPILE_FILE.COM command procedure, C-27 
Sample execution, C-28 
Compressing files 
in Mail, 6-23 
Concatenating 

character strings, 14-5 
symbol names, 14-5 
Condition codes 

as symbol $SE VERITY, 15-52 
as symbol $STATU S, 15-51 
definition, 15-51 
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Conditionals in command procedures 
assigning, 15-65 
CONNECT command 

/CONTINUE qualifier, 17-7 
/LOGOUT qualifier, 17-8 
Continuation 

of character stings over multiple lines, 14-7 
of multiple command lines, 14-3,15-15 
CONTINUE command, 17-4 

in command procedure after Ctrl/Y, 15-58 
in EDT, 9-7 
Control characters 
ASCII values, D-2 
Control keys 
See Ctrl keys 

Controller designation field 
default value, 12-7 
definition, 12-8 
Conversation text 
in Phone, 7-2 

CONVERT.COM command procedure, C-2 
Sample execution, C-6 
Converting from EDT to EVE, A-34 
COPY command, 4-9, 12-8 
in Mail, 6-10 

moving text in EVE with, 8-18 
/SI NCE qualifier, 4-9 
Copying text 
in EDT, 9-12 
in EVE, 8-19 
CREATE command, 4-9 

/DIRECTORY qualifier, 5-3, 5-6 
/NAME_TABLE qualifier, 13-9 
/TABLE qualifier 

/PROTECTION qualifier, 13-10 
/QUOTA qualifier, 13-10 
Creating EVE section files, A-20 
Ctrl keys, 3-14 to 3-16 
common, 3-2 
Ctrl/A key sequence, 3-15 

changing EVE editing mode with, 8-11 
Ctrl/B key sequence, 18-5 

recalling commands with, 3-11, 3-15 
Ctrl/C key sequence, 3-15 

canceling EDT command with, 9-5 
canceling Mail messages with, 6-4, 6-7 
Ctrl/E key sequence, 3-15 

moving the EVE cursor with, 8-8 
Ctrl/H key sequence 

moving the EVE cursor with, 8-8 
Ctrl/I key sequence 

formatting EVE text with, 8-34 
Ctrl/J key sequence 

erasing EVE text with, 8-13 
Ctrl/L key sequence 

formatting EVE text with, 8-34 


Ctrl/M key sequence 

formatting EVE text with, 8-34 
Ctrl/T key sequence, 3-15 

checking the status of processes, 2-17 
interrupting DCL commands with, 3-15 
Ctrl/U key sequence, 3-14 
erasing EVE text with, 8-13 
Ctrl/V key sequence 

inserting characters in EVE with, 8-11 
inserting escape characters in EVE, 8-12 
Ctrl/W key sequence 

refreshing screen display in EDT with, 9-7 
refreshing screen displays with, 3-15, 17-4 
Ctrl/Y key sequence, 3-15 

aborting remote sessions with, 2-20 
action taken during execution, 15-57 
defaults in nested procedures, 15-61 
disabling, 15-62 

enabling SET VERIFY with, 15-21 
flow of execution, 15-60 
interrupting a command procedure with, 

15-51, 15-58 

interrupting an EDT editing session with, 9-7 
interrupting images with, 17-4 
interrupting or canceling DCL commands with, 
3-15 

with ON command, 15-59 
Ctrl/Z key sequence, 3-14 

as end-of-fi I e terminator, 3-14,4-9 
sending files in Mail with, 6-7 
sending Mail messages with, 6-4 
writing files in EDT with, 9-5 
Cursor control 
in EVE, 8-7 
Customizing 

EVE editing sessions, A-31 
in Mail, 6-21 
CUT command 

moving text in EVE with, 8-17 

D 

$DEFAULTS$ buffer, A- 11 
Data 

logical, 14-14, 14-15 
numeric, 14-11 to 14-12 
passing to command procedure, 15-8 
Data types 

using lexical functions with, 16-14 
Dates 

See also Absolute time 
See also Combination time 
See also Delta time 

specifying absolute and delta date and time 
combinations, 3-10 
specifyi ng absol ute date and ti me, 3-9 
specifying delta date and time, 3-10 
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DCL (DIGITAL Command Language), 1-1 
See also DCL commands 
definition, 2-1 
DCL commands 
abbreviating 

in command procedures, 3-5 
case sensitivity, 3-1 
constructing, 3-2 
defaults, 3-4 
entering, 3-1 
interrupting or canceling 
with Ctrl/T, 3-15 
with Ctrl/Y, 3-15 
overriding with symbols, 14-3 
pa ra meters, 3- 4 to 3- 7 
prompt, 3-3 
qualifiers, 3-7 to 3-9 
recalling, 3-15 

with Down arrow key, 3-15 
rules for entering, 3-5 
syntax, 1-4, 3-2, 3-4 
verbs, 3-3 
DCL Help 

See HELP command 
.DDIF files 
in Mail, 6-6 

DEALLOCATE command, 12-3 
DEASSIGN command, 13-16 

deleting logical name tables, 13-16 
/TABLE qualifier, 13-7 
Debugger 

logical name for the default input stream, 
13-13 

logical name for the default output stream, 
13-14 
Debugging 

DECTPU, A- 17 
within EVE, A- 17 

DEC Multinational character set, B-2 
DECK command, 15-7, 15-13 
DECnet 

See also Networks 
access string, 7-2 
access violations, 4-10 
and logical node names, 13-3 
logging in to remote systems with, 1-2 
manipulating files with, 4-10 
specifying full node names, 4-5 
DECnet for OpenVMS 
See DECnet 
DECTPU 

debugging, A- 17 
executing commands, A- 18 
saving EVE defaults in command files, A-8 
DECTPU editor 
See EVE 


DECTPU procedures, A-l 
compiling, A- 18 
extending EVE with, A- 18 
rules for writing, A-18 
using EXTEND EVE command to compile, 

A- 19 

Defaults, 3-4 
definition, 2-16 
file protection, 18-4 
settings in EVE, A-8 
values provided by system, 3-4 
DEFINE command, 13-2 

example with access mode qualifier, 13-7 
/KEY qualifier in Mail, 6-16 
in initialization file, 6-17 
specifying access modes with, 13-7 
/TABLE qualifier, 13-7, 13-9 
/TRANSLATI ON_ATTRI BUTES qualifier, 13-5 
/USERJMODE qualifier, 13-16 

defining SYS$I NPUT with, 17-11 
in command procedures, 15-12 
redefining SYS$I NPUT with, 13-18 
redefining SYS$OUTPUT with, 13-18 
using to redirect output, 15-16 
DEFINE KEY command 
in EVE, A-2, A-34 
in EVE initialization files, A-3 
Defining keys 
in EVE, A-l 

in EVE initialization files, A-3 
to execute EVE commands, A-2 
DELETE BUFFER command 

for EVE buffer manipulation, 8-37 
keywords used with in EVE, 8-39 
DELETE command, 4-12 

and wildcard characters, 4-12 
/CONFIRM qualifier, 4-12 
/ENTRY qualifier, 4-14,17-15 
in EVE, 8-14 
in Mail, 6-12 
/LOG qualifier, 4-12 
/SYMBOL qualifier, 14-5 
using with F$SEARCH lexical function, 16-9 
Delete key, 3-14,3-15 

erasing text in EVE with, 8-13 
DELETE WINDOW command 

in EVE window environment, 8-42 
Delta time 

combined with absolute time, 3-10 
default values, 3-10 
rules for entering, 3-10 
syntax, 3- 10 

DEPOSIT command, 14-27 
Detached processes 
batch job as, 1-3 
definition, 1-8 
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Device code field 

in VMScluster device names, 12-8 
Device field, 4-1 
Device names 

See also Device field 

See also Physical device names 

See also VMScluster device names 

concealed, 13-4 

generic, 12-7 

logical names equated to, 12-7 
terminal, 13-5 
Devices, 1-6, 12-1 
identifying, 12-6 
mass storage, 1-6 

obtaining information about using F$DEVI 
lexical function, 16-8 
record oriented, 1-6 
unit record, 1-6 
Diacritical marks 
in EVE, 8-24 
Dialup lines 

control I i ng access to, 2-4 
using in a public area, 2-21 
Dialups 

breaking connections, 2-21 
login failures, 2-10 
logins, 2-7 

DIGITAL Command Language 
See DCL 

DIGITAL Standard Runoff 
See DSR 

Dl R.COM command procedure, C-9 
Sample execution, C-10 
Directories, 1-4 

creating logical names for, 13-1 
default login, 1-5 
definition, 5-1 

searching using F$SEARCH, 16-8 
DIRECTORY command, 5-3 
in Mail, 6-3, 6-10 
Directory field 
definition, 4-1 

using a percent sign (%) wildcard character in, 
4-8 

using an asterisk (*) wildcard character in, 

4-7 

Directory files 

See also Directory structures 

creating, 5-3 

default, 1-5, 5-4 

deleting, 5-5 

login, 1-5 

named format, 5-3 

protection, 5-6 

setting default to another, 5-4 
top-level, 1-5, 5-1 


Directory names 

named format in file specifications, 5-3 
replacing 

with ellipsis ( ... ) wildcard character, 5-7 
with hyphen (-) wildcard character, 5-8 
translating U I C format to named format, 5-9 
Directory specifications 
definition, 5-3 
rules for entering, 5-3 
Directory structures 

master file directory in, 1-5 
sample, 5-1 
subdirectories in, 1-5 
top-level directory in, 1-5 
user file directory in, 1-5 
.DIS file type 

with distribution lists, 6-6 
Disconnected job messages, 2-6 
Disconnected processes 
See Virtual terminals 
Disks, 1-5, 1-6 
See also Devices 
allocating to processes, 12-2 
contents of, 1-5, 1-6 
deallocating drives, 12-3 
mounting, 12-5 
volume sets 

See Volume sets 
DISMOUNT command, 12-8 
See also MOUNT command 
deallocating a device, 12-9 
/NOUNLOAD qualifier, 12-8 
Dismounting volumes, 12-8,12-9 
Displaying EVE command lists, 8-2 
Displaying files in directories, 5-3 
Distribution lists 

creating with an editor, 6-5 
in Mail, 6-6 

sending mail to from DCL level, 6-6 
sending to in mail, 6-5, 6-6 
using in Mail, 6-6 

Documentation comments, sending to Digital, iii 
Dollar sign ($) 

as DCL prompt, 2-2, 3-1 
in command procedures, 15-7 
in equivalence strings, 13-2 
in file names, 4-2 
in symbol definitions, 14-4 
in VMScluster device specifications, 12-8 
i ncl udi ng as data, 15- 13 
Down arrow key 

moving the cursor with in EVE, 8-8 
recalling commands with, 3-11,3-15 
DSR (DIGITAL Standard Runoff) 
defaults, 10-3 
description, 10-1 
entering commands, 10-1 
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DSR (DIGITAL Standard Runoff) (cont'd) 
table of all commands in, 10-9 
DSR commands 
abbreviating, 10-1 
RUNOFF command, 10-1 
Dual-pathed device specifications, 12-8 

E 

EBCDIC collating sequence, 11-6 
Echoing 

inhibiting, 17-5 
when typing password, 2-4 
with defined keys in Mail, 6-22 
EDIT command, 9-1 
/EDT qualifier 

/READ_ONLY qualifier, 4-11 
/RECOVER qualifier in EDT, 9-7 
/TPU qualifier, 8-29, A-33 
/CREATE qualifier, A-17 
/DEBUG qualifier, A-17 
invoking EVE with, 8-7 
/MODIFY qualifier, 8-29 
/READ_ONLY qualifier, 4-11 
/RECOVER qualifier 

with buffer-change journal file, 8-32 
/SECTION qualifier, A-32 
/START_POSITI ON qualifier, 8-28 
without journaling, 8-33 
/WORK qualifier, 8-28 
EDITALL.COM command procedure, C-14 
Sample execution, C-16 
Editing buffers 

editing two files within two EVE buffers, 8-43 
Editing command lines, 3-13 
deleting lines, 3-14 
enabling line editing, 3-13 
insert mode, 3-13 
overstrike mode, 3-13 
Editing files 

using EDT, 9-1 
using two EVE buffers, 8-43 
Editing sessions 
See also EDT editor 
See also EVE 

beginning in EVE with new file names, 8-3 

changing modes in EVE, 8-11 

customizing, A- 31 

ending in EVE, 8-6 

exiting from EDT, 9-5 

in EVE, 8-7 

recovering EDT after system interruption, 9-7 
refreshing screen display during EDT, 9-7 
Editors 

See EDT editor 
See EVE 


EDT editor 

buffer definition, 9-1 
changing modes in, 9-6 
displaying files with, 9-2 
edit modes in, 9-6 
entering commands, 9-7 
exiting from, 9-5 
invoking, 9-1 
keypad commands, 9-4 
line-editing commands, 9-2, 9-6 
recovering session after system interruption, 
9-7 

summary of commands in, 9-8 
EDT files 

converting to EVE, A-34 
EDT keypad option 
in EVE, A-34 
Ellipsis ( ... ) 

wildcard character in directory names, 5-7 
wildcard character with EVE filenames, 8-29, 
8-40 

ELSE command, 15-34 
END OF LINE command 

moving the EVE cursor with, 8-8 
ENDIF command, 15-34 
ENDSUBROUTINE command, 15-43 
ENLARGE Wl N DOW command 
in EVE, 8-42 
Enter key 

using in EVE, 8-11 
Environmental identifiers 
example, 18-2 
EOB symbol, 9-2 
EOD command, 15-7, 15-13 
Equal sign ( =) 

defining symbols with, 14-4 
Equivalence strings, 1-7,13-1 

equating multiple logical names to, 13-5 
ERASE CHARACTER command 
erasing text with in EVE, 8-14 
ERASE LINE command 

erasing text with in EVE, 8-14 
ERASE PREVIOUS WORD command 
erasing text in EVE with, 8-14 
ERASE START OF LINE command 
erasing text in EVE with, 8-14 
ERASE WORD command 

erasing text in EVE with, 8-14 
Error conditions 

See also System messages 
determining severity level, 15-52 
Error handling 

actions for different severity levels, 15-54 
disabling Ctrl/Y, 15-57 
disabling error checking, 15-56 
in command procedures, 15-51 
overriding using ON command, 15-54 
with ON command, 15-54 
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Error messages 

See System messages, error 
Errors 

locating in command procedures using SET 
VERIFY, 15-19 
Escape characters 

inserting in EVE, 8-12 
EVE 

as default Mail editor, 6-14 

assigning multiple definitions to keys, A-6 

command line editing, 8-27 

copying text, 8-19 

creating buffers, 8-40 

creating command symbols for, 8-6 

creating scratchpads, 8-39 

creating subprocess, 8-43 

customizing editing sessions, A-31 

defining keys, A-2 

defining keys to execute commands, A-2 
defining keys with LEARN, A-7 
entering commands, 8-5 
erasing text, 8-13 
extending, A- 18 
finding text, 8-22 
formatting text, 8-34 
getting started with, 8-7 
inserting text, 8-11,8-16 
leaving subprocess, 8-43 
marking locations, 8-25 
modes of editing, 8-4 
movi ng text, 8- 16 
moving the cursor, 8-7 
reaching DCL, 8-43 
reading batch job log files with, 17-11 
reading files into EVE buffer, 8-41 
removing key definitions, A-3 
replacing text, 8-13,8-26 
source code, A- 18 
startup files, A-l 
table of key names, A-4 
using buffers, 8-36 
using windows, 8-41 
writing DECTPU procedures for, A- 18 
EVE attributes 

saving in command files, A-33 
saving in section files, A- 29 
EVE command files 
See Command files 
EVE commands 
ATTACH, 8-43 
BOTTOM, 8-8 
BOX COPY, 8-20 
BOX CUT, 8-20 
BOX CUT INSERT, 8-20 
BOX CUT OVERSTRIKE, 8-20 
BOX PASTE, 8-20, 8-21 
BOX PASTE INSERT, 8-20 


EVE commands (cont'd) 

BOX PASTE OVERSTRIKE, 8-20 
BOX SELECT, 8-19 to 8-21 
BUFFER, 8-36 
CAPITALIZE WORD, 8-34 
CENTERLINE, 8-34 
CHANGE DIRECTION, 8-8 
CHANGE MODE, 8-11 
COPY, 8-18 
CUT, 8-17 
DEFINE KEY, A-34 
DELETE, 8-14 
DELETE BUFFER, 8-37 
DELETE WINDOW, 8-42 
END OF LINE, 8-8 
ENLARGE WINDOW, 8-42 
ERASE CHARACTER, 8-14 
ERASE LINE, 8-14 
ERASE PREVIOUS WORD, 8-14 
ERASE START OF LINE, 8-14 
ERASE WORD, 8-14 
EXIT, 8-6 
EXTEND EVE, A- 19 
EXTEND THIS, A- 19 
FILL, 8-35 

FILL PARAGRAPH, 8-35 
FILL RANGE, 8-35 
FIND, 8-22 
FIND NEXT, 8-22 
FIND SELECTED, 8-23 
FORWARD, 8-8 
GET FILE, 8-37 
GO TO, 8-8, 8-25, 8-37 
HELP, 8-2 

INCLUDE FILE, 8-11,8-37 
INSERT HERE, 8-17 
INSERT MODE, 8-11 
INSERT PAGE BREAK, 8-35 
LEARN, A-7, A-36 
LINE, 8-8 

LOWERCASE WORD, 8-35 

MARK, 8-8, 8-25 

MOVE BY LINE, 8-9 

MOVE BY PAGE, 8-9 

MOVE BY WORD, 8-9 

NEW, 8-37 

NEXT BUFFER, 8-37 

NEXT SCREEN, 8-9 

NEXT WINDOW, 8-9,8-42 

ONE WINDOW, 8-42 

OPEN, 8-37 

OPEN SELECTED, 8-37 

OVERSTRIKE MODE, 8-11 

PAGINATE, 8-35 

PASTE, 8-17 

PREVIOUS SCREEN, 8-9 

PREVIOUS WINDOW, 8-9,8-42 

QUIT, 8-7 
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EVE commands (cont'd) 

QUOTE, 8-11 
REMOVE, 8-17,8-37 
RESET, 8-17 
RESTORE, 8-14 

RESTORE BOX SELECTION, 8-20,8-22 
RESTORE CHARACTER, 8-15 
RESTORE LINE, 8-15 
RESTORE SELECTION, 8-15, 8-17, 8-22 
RESTORE WORD, 8-15 
REVERSE, 8-9 

SAVE ATTRIBUTES, A- 2, A-7, A-28, A-29, 

A- 32 

SAVE EXTENDED EVE, A-2, A-7, A-29 

SAVE FILE, 8-37 

SAVE FILE AS, 8-37 

SAVE SYSTEM ATTRIBUTES, A-28 

SELECT, 8-18,8-37 

SELECT ALL, 8-18 

SET BOX NOPAD, 8-20, 8-22 

SET BOX NOSELECT, 8-20 

SET BOX PAD, 8-20, 8-22 

SET BOX SELECT, 8-20,8-21 

SET BUFFER, 8-38 

SET CURSOR BOUND, 8-9, A- 34 

SET CURSOR FREE, 8-9 

SET DEFAULT COMMAND FILE, A-29, A- 33 

SET DEFAULT SECTION FILE, A-29, A- 32 

SET EXIT ATTRIBUTE CHECK, A-29 

SET FIND, A- 35 

SET FIND CASE EXACT, 8-23 

SET FIND CASE NOEXACT, 8-23 

SET FIND NOWHITESPACE, 8-23 

SET FIND WHITESPACE, 8-23 

SET GOLD KEY, A-2 

SET KEYPAD EDT, A-34 

SET LEFT MARGIN, 8-35 

SET NODEFAULT COMMAND FILE, A-29 

SET NODEFAULT SECTION FILE, A-29, 

A- 32 

SET NOEXIT ATTRIBUTE CHECK, A-29 
SET NOGOLD KEY, A-2 
SET NOPENDING DELETE, 8-18 
SET NOSECTION FILE PROMPTING, A-29, 
A- 32, A- 33 

SET NOSHIFT KEY, A-2 

SET NOWRAP, 8-36 

SET PARAGRAPH INDENT, 8-36 

SET PENDING DELETE, 8-18 

SET RIGHT MARGIN, 8-35, A- 35 

SET SCROLL MARGINS, 8-10, A-35 

SET SECTION FILE PROMPTING, A-29, 

A- 32 

SET SHIFT KEY, A-2 
SET TABS AT, 8-36 
SET TABS EVERY, 8-36 
SET TABS INSERT, 8-36 
SET TABS INVISIBLE, 8-36 


EVE commands (cont'd) 

SET TABS MOVEMENT, 8-36 
SET TABS SPACES, 8-36 
SET TABS VISIBLE, 8-36 
SET WIDTH, 8-42 
SET WILDCARD VMS, 8-23 
SET WRAP, 8-36 
SHIFT LEFT, 8-10,8-42 
SHIFT RIGHT, 8-10,8-42 
SHOW, 8-38 
SHOW BUFFERS, 8-38 
SHOW DEFAULTS BUFFERS, 8- 
SHOW SYSTEM BUFFERS, 8-38 
SHOW WILDCARDS, 8-23 
SHRINK WINDOW, 8-42 
SPAWN, 8-43 
SPLIT WINDOW, 8-42 
START OF LINE, 8-10 
STORE TEXT, 8-18 
TOP, 8-10 
TPU, A- 18 

TWO WINDOWS, 8-42 
UNDEFINE KEY, A-3 
UPPERCASE WORD, 8-36 
WILDCARD FIND, 8-23 
WRITE FILE, 8-38 
EVE editing keys 
Ctrl/A, 8-11 
Ctrl/E, 8-8 
Ctrl/H, 8-8 
Ctrl/I, 8-34 
Ctrl/J , 8-13 
Ctrl/L, 8-34 
Ctrl/M, 8-34 
Ctrl/U, 8-13 
Ctrl/V, 8-11 
Delete key, 8-13 
down arrow, 8-8 
Find key, 8-23 
GOLD down arrow, 8-8 
GOLD F 13, 8-13 
GOLD Insert Here, 8-13 
GOLD left arrow, 8-8 
GOLD Next Screen, 8-8, 8-41 
GOLD Prev Screen, 8-8, 8-41 
GOLD Remove, 8-17 
GOLD right arrow, 8-8 
GOLD Select, 8-17 
GOLD up arrow, 8-8 
I nsert H ere, 8- 16 
left arrow, 8-8 
Remove, 8-16 
Return, 8-34 
right arrow, 8-8 
Select, 8-16 
Tab, 8-34 
up arrow, 8-8 
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EVE files 

converting from EDT, A-34 
recovering, 8-32 
EVE initialization files 
See I nitialization files 
EVE key names, A-3 
table of, A- 4 
EVE section files 
See also Section files 
saving attributes in, A-29 
EVE$INIT.EVE file, A-27 
EXAMINE command, 14-27 
Exchanging messages 
in Mail, 6-18 
in Phone, 7-3 
Exclamation point ( ! ) 

as comment flag character in DSR, 10-18 
in command procedures, 15-7 
in distribution lists, 6-5 
in Sort specification files, 11-12 
Executable images, 1-8 
See also Images 
See also Programs 

Execute procedure ( @) command, 15-2 
See also At sign (@) 

Executing command procedures 
using at sign (@), 15-2 
EXIT command, 15-6, 15-50 
in EDT, 9-5 
in EVE, 8-6 
in Mail, 6-2 

passing status values with, 15-52 
Exiting 

from command procedures, 15-6 
from EDT, 9-5 
from EVE, 8-6 
from Mail, 6-23 
Expirations 

of accounts, 2-14 
of passwords, 2-13 
of secondary passwords, 2-13 
Expressions 

character, 14-8 
definition, 14-6 
evaluating, 14-27 
iterative substitutions, 14-28 
logical, 14-15 
numeric, 14-12 
precedence of operators, 14-18 
rules for determining values of, 14-19 
EXTEND EVE command 

using to compile DECTPU procedures, A- 19 
EXTEND THIS command, A- 19 
Extensible Versatile Editor 
See EVE 


EXTRACT command 
in Mail, 6-8 

F 

F$CONTEXT lexical function, 16-6 
F$CVTI ME lexical function, 16-11 
F$DI RECTORY lexical function, 14-18 
F$ELEMENT lexical function, 15-46, 15-47 
with F$EXTRACT, 16-11 
F$ENVIRONMENT lexical function, 15-69, 16-1 
changing default file protections with, 16-4 
obtaining current defaults, 16-4 
SYMBOL_SCOPE argument, 14-22 
VE RB_SCOPE argument, 14-22 
F$EXTRACT lexical function, 15-20, 15-45, 

16-11 

extracting a string, 16-11 
F$FAO lexical function, 16-12 
defining record fields, 16-13 
F$FI LE_ATTRI BUTES lexical function, 16-9 
F$GETEXAMPLE lexical function, 16-5 
F$GETJ PI lexical function, 15-69, 16-6 
F$GETQUI lexical function, 16-5 
obtaining queue information, 16-5 
F$GETSYI lexical function 

obtaining system or VMSduster information, 
16-5 

F$l NTEGER lexical function, 14-20 
converting data types, 16-14 
evaluating data, 16-14 

F$LENGTH lexical function, 14-17, 15-48, 16-10 
with F$LOCATE, 16-10 
F$LOCATE lexical function, 15-48, 16-10 
with F$LENGTH, 16-10 
F$LOGICAL lexical function, 16-9 
See also F$TRNLNM lexical function 
F$MESSAGE lexical function, 15-33 
F$MODE lexical function, 2-7, 15-71 
in login procedures, 17-10 
F$PARSE lexical function, 16-9, 16-11 
F $P I D lexical function, 16-6 

obtaining process identification, 16-6 
F$SEARCH lexical function, 15-24 

avoiding command procedure errors, 16-9 
searching for files, 16-8 
using with DELETE command, 16-9 
F$STRING lexical function, 14-20 
converting data types, 16-14 
F$TRNLNM lexical function, 16-9 
translating logical names, 16-9 
F $TY P E lexical function, 14-20, 16-15 
F$VERIFY lexical function, 15-20, 16-3 
F 6 to F 14 keys, 3- 14 to 3- 16 
Feedback on documentation, sending to Digital, iii 
Fields, 11-2 
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File access 

from remote notes, 4-6 
on volume sets, 12-7 
using control strings, 4-6 
File browsers, 18-9 
FILE command 
in Mail, 6-9 
Filenames, 4-1 

rules for entering, 4-1 
specifying a list of, 5-5 
using a percent sign (%) wildcard character in, 
4-8 

using an asterisk (*) wildcard character in, 

4-7 

valid characters in, 4-1 
with null values, 4-8 
File protection, 4-12 

changing default with F$ENVI RON ME NT 
lexical function, 16-4 
File specifications, 1-5,13-6 
See also Wildcard characters 
alternate form for magnetic tapes, 4-8 
as multiple search lists, 13-23 
as search lists, 13-5, 13-6, 13-22, 13-23 
creating logical names for, 13-2 
default values created by logical name 
translations, 13-21 
list of included fields, 4-1 
logical names in, 1-7, 13-1 
networks, 4-6 
node names, 4-4,4-10 
File type field, 4-1 

asterisk (*) wildcard character in, 4-7 
default values created by logical name 
translations, 13-21 

using a percent sign (%) wildcard character in, 
4-8 

with null values, 4-8 
File types, 4-2 

I i st of defau I ts, 4- 2, 4- 3 
rules for entering, 4-2 
File version numbers, 4-1, 4-3 

using an asterisk (*) wildcard character in, 

4-7 
Files, 1-4 

See also Directory files 

adding ACEs for security auditing, 18-9 

applying an alarm to, 18-9 

auditing access, 18-7,18-9 

copying, 4-9 

copying between nodes, 4-10 
copying from remote account, 18-7 
copying using access control strings, 4-14 
creating DECTPU command files in EVE, A- 17 
creating from Mail messages, 6-8 
creating in command procedures, 15-23 
creating logical names for, 13-1 


Files (cont'd) 

deciding when to use security auditing, 18-9 

definition, 4-1 

di spl ayi ng contents of, 4- 11 

editing in EVE, 8-29 

initialization, 6-17 

MAIL. MAI, 6-9 

merging, 11-8 

merging multiple, 1-6 

modifying in command procedure, 15-28 

naming, 4-1 

open file quota, 15-69 

process-permanent, 13-12 

protection of, 6-13 

protection of confidential, 18-9 

protection required for proxy access, 18-7 

purging, 4-12 

reading from command procedure, 15-26 
renaming, 4-10 

restrictions when sending in Mail, 4-10 
sequence checking, 11-9 
sorting, 1-6 
using Mail to send, 6-6 
versions controlled with A/ERSION_LIMIT 
qualifier, 4-4 

writing in command procedures, 15-23 
Files- 11 On-Disk Structure, 12-4 
FILL command 

formatting EVE text with, 8-35 
FILL PARAGRAPH command 
formatting EVE text with, 8-35 
FILL RANGE command 

formatting EVE text with, 8-35 
FIND command 

in EVE, 8-22, 8-23 
Find key 

in EVE, 8-23 
FIND NEXT command 

finding text in EVE with, 8-22 
in EVE, 8-24 

FIND SELECTED command 
finding text in EVE with, 8-23 
in EVE, 8-24 
Foreign commands, 14-1 

default image file specifications, 14-4 
definition, 14-4 
parsing in command lines, 14-4 
syntax, 14-4 

using equal sign (=) to define, 14-4 
Foreign file specifications 
on networks, 4-6 
Foreign volumes 

See also MOL) NT command 
mounting, 12-5 
F orm feeds 

customizing in EDT, 9-15 
inserting in EDT, 9-9 
inserting in EVE, 8-35 
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Forms 

description, 4-14 

FORTUSER.COM command procedure, C-17 
Sample execution, C-19 
FORWARD command 
in Mail, 6-9 

moving the EVE cursor with, 8-8 
Found ranges 
in EVE, 8-22 
Full names, 4-5 
Function keys, 3- 14 to 3- 16 
predefined in EVE, 8-5 
setting mode of in EVE, A-8 
VT200 series terminals, 4-11, D-l 
VT300 series terminals, D-l 

G 

General identifiers 
example, 18-2 

Generated passwords, 2-11, 2-12 
example, 2-11 
Generic device names 
definition, 12-7 
GET FILE command 

creating new EVE buffers with, 8-40 
for EVE buffer manipulation, 8-37 
reading files into EVE buffer with, 8-41 
$GETDVI lexical function, 16-8 
GETPARMS.COM command procedure, C-12 
Sample execution, C-14 
Global symbol tables (GSTs) 

See also Local symbol tables 
DCL reserved symbols, 14-21 
definition, 14-21 
in the search order, 14-21 
Global symbols 

See also Global symbol tables (GSTs) 
command levels available to, 14-2 
creating in command procedure, 15-17 
Global variables 

in DECTPU procedures, A- 19 
parts of, A- 19 
GO TO command 
in EVE, 8-25, 8-37 
moving the EVE cursor with, 8-8 
GOLD down arrow key sequence 
moving the EVE cursor with, 8-8 
GOLD F13 key sequence 

erasing text in EVE with, 8-13 
GOLD I nsert Here key sequence 
erasing text in EVE with, 8-13 
GOLD key 

canceling key press, A-7 

creating your own key combinations for, A-6 

defining in EVE, A-6 

defining in initialization files, A-7 


GOLD key (cont'd) 
in EDT, 9-4 

list of default GOLD key combinations, A-6 
GOLD left arrow key sequence 
moving the EVE cursor with, 8-8 
GOLD Next Screen key sequence 
in EVE window environment, 8-41 
moving the EVE cursor with, 8-8 
GOLD Prev Screen key sequence 
in EVE window environment, 8-41 
moving the EVE cursor with, 8-8 
GOLD Remove key sequence 
moving text in EVE with, 8-17 
GOLD right arrow key sequence 
moving the EVE cursor with, 8-8 
GOLD Select key sequence 

moving text in EVE with, 8-17 
GOLD up arrow key sequence 

moving the EVE cursor with, 8-8 
GOSUB command, 15-41 

with the IF. ..THEN language construct, 15-40 
GOTO command, 15-35 
with labels, 15-39 

with the IF. ..THEN language construct, 15-39 
Group logical name tables 
See also Logical name tables 
definition, 13-13 
logical names for, 13-13 
Group users (security category), 18-3 
GRPNAM privilege 

using to edit group name tables, 13-8 
GRPPRV privilege 

using to edit group name tables, 13-8 

H 

Hardcopy output, disposal of, 2-21 
Hardcopy terminals 

logout considerations, 2-21 
HELP command, 2-17 

displaying command list in EVE, 8-2 
in EDT, 9-5 
in EVE, 8-2 
in Mail, 6-1 

with specific commands in EVE, 8-3 
Help facility 
in EDT, 9-5 
in EVE, 8-2 

HELP KEYPAD command, A-6 
HELP/MESSAGE command, 2-18 
Hierarchical directory structures 
definition, 1-5 
Hold Screen key, 4-11 
Hyphen (-) 

as command line continuation, 3-6, 14-3, 
14-7, 15-15 

in a directory name, 5-8 
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I 

I/O errors 

in command procedures, 15-32 
I dentifiers 

displaying process, 18-1 
environmental, 18-2 
general, 18-2 
UIC, 18-2 

IF command, 14-27, 14-28 

evaluating input of INQUIRE command, 15-37 
executing a block of commands after, 15-38 
restrictions to the IF-THEN-ELSE construct, 
15-36 

testing severity level, 15-52 
with GOSUB command, 15-40 
with GOTO command, 15-39 
I mages 

See also Command images 
See also Foreign commands 
command, 1-4 
definition, 1-8 
INCLUDE FILE command 
in EVE, 8-11,8-37 

reading files into EVE buffer with, 8-41 
Indexed sequential files, 11-6 
I ndexed sorti ng, 11- 14 
See also Sort/Merge utility 
reasons for selecting, 11-14 
I ndexes 

creating in DSR, 10-6 
Informational messages 

See System messages, informational 
I nitialization files, 6-17 

for EVE default settings, A- 11 
in EVE, A-l 

saving EVE attributes in, A-3, A-30, A-31 
with the SET RIGHT MARGI N command in 
EVE, A- 35 

INITIALIZE command, 12-3 
See also Volumes 

Files- 11 On-Disk Structure, 12-4 
I nitializing 

disk volumes, 12-4 
magnetic tape volumes, 12-4 
volumes, 12-3 
Input 

opening a file to accept, 15-22 
to batch jobs, 17-10 
I nput files 

temporary defaults in a parameter list, 5-5 
I nput streams 
definition, 13-12 
INQUIRE command, 15-8, 15-11 

evaluating input from using the I F command, 
15-37 


INQUIRE command (cont'd) 

using to obtain a value for a variable, 15-64 
I nsert H ere buffer 

contents of in EVE, 8-16 
INSERT HERE command 

moving text in EVE with, 8-17 
I nsert H ere key 

moving text in EVE with, 8-16 
I nsert mode 

definition, 3-13 
in EVE, 8-11 
INSERT MODE command 
in EVE, 8-11 

INSERT PAGE BREAK command 
formatting EVE text with, 8-35 
I nteger variables 

in DECTPU procedures, A- 19 
I ntegers 

See Numbers 
I nteractive logins, 2-7 
classes, 2-7 
I nteractive mode 
definition, 1-3 
processes, 2-7 
I ntermediate files 
in DSR, 10-7 

Iterative substitutions, 14-27 

during three phases of command processing, 
14-26 

in expressions, 14-28 
using apostrophes, 14-27 
using command synonyms, 14-28 
Iterative translations, 13-4 

See also Logical name translations 
definition, 13-21 
preventing, 13-5 

J 

J ob controllers 

affected by shift restrictions, 2-9 
J ob logical name tables 

criteria for determining quota, 13-11 
default contents of, 13-12 
logical names for, 13-12 
J ob logical names 
definition, 13-12 
in job trees, 13-12 
J ob terminations 

imposed by shift restrictions, 2-9 
J ob trees 

definition, 17-3 
J ournal files 

deleting in EVE, 8-33 
directory for in EVE, 8-31 
in EDT, 9-7 
in EVE, 8-30 to 8-32 
naming in EVE, 8-32 
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J ournaling 

buffer -change in EVE, 8-30 to 8-34 
disabling in EVE, 8-30 
in EDT, 9-7 

K 

Key definitions 
assigning, 3-14 
in EVE, A-2 

in EVE initialization files, A-3 
in Mail, 6-16 
Key names 

See also Keypads 
See also Keys 
in EVE, A-3 
in Mail, 6-16 
Key sequences, 3-2 
Keypads 

default editing keys for EVE, 8-5 
default in Mail, 6-16 
defining in Mail, 6-17 
EDT option in EVE, 8-6 
in EDT, 9-4 

using the mini keypad in EVE, 8-5 
WPS option in EVE, 8-6 
Keys, 1-6 

See also Key definitions 
function, 3-14 to 3-16 
specifying, 11-3 

using in the Sort/Merge utility, 11-4 
Keywords, 3-4 

L 

Label scoping, 15-43 
Labels 

definition, 3-4 

duplicates in command procedures, 15-41 
error handling, 15-53 
in DCL command lines, 3-2 
rules for entering in subroutines, 15-41 
with GOSU B command, 15-41 
with GOTO command, 15-39 
with THEN or ELSE commands, 15-36 
Last login messages, 18-8 
LEARN command, A-7, A-36 
Learn sequences 

assigning to keys, A-7 
canceling, A-7 
in EVE, A-l 
saving, A-7 
Left arrow key 

moving cursor with in DCL command line, 
3-15 

moving the cursor with in EVE, 8-8 


Lexical functions, 1-4, 1-8, 16-1 

changing process characteristics with, 16-2 

evaluating, 14-18 

F$CONTEXT, 16-5 

F$DI RECTORY, 14-18 

F$LENGTH, 14-17 

list of functions used to save and restore process 
characteristics, 15-69 
manipulating character strings with, 16-10 
manipulating data types with, 16-14 
obtaining information about files and devices, 
16-8 

obtaining process information with, 16-2 
obtaining system information with, 16-5 
rules for using, 14-17 
symbol substitution in, 14-23 
syntax, 14-16 

translating logical names with, 16-9 
using in command procedures, 14-16, 15-15 
with WRITE command, 15-25 
Lexical input phase 

See Command input scanning 
L ifeti me of accounts, 2- 14 
L ifeti me of passwords, 2- 10 
LINE command 

moving the EVE cursor with, 8-8 
Line editing, 3-13 
Line mode 

line numbers in E DT, 9-2 
specifying a range in EDT, 9-3 
Linefeed key, 3-16 

LISTER.COM command procedure, C-20 
Sample execution, C-21 
Listing files in directories, 5-3 
Lists 

See Distribution lists 
LNM$FI LE_DEV logical name 
default precedence order, 13-6 
redefining the search order, 13-9 
LNM$GROUP logical name, 13-13 
LNM$J OB logical name, 13-12 
LNM$PERMANENT_MAI LBOX logical name, 
13-13 

LNM$PROCESS logical name, 13-16 
LNM$PROCESS_DI RECTORY logical name, 

13-11 

LNM$SYSTEM logical name, 13-13 
LNM$SYSTEM_DI RECTORY logical name, 13-11 
LNM$TEMPORARY_MAI LBOX logical name, 
13-15 

Local nodes, 1-2 
Local symbol tables 

See also Global symbol tables 
See also Local symbols 
See also Symbols 
definition, 14-20 
in the search order, 14-21 
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Local symbol tables (cont'd) 

PI to P8, 14-21 
Local symbols, 14-2 
See also Global symbols 
See also Local symbol tables 
LOCKPWD flag, 2-5 
Log files, 17-9 
contents of, 17- 11 

examining during execution of batch jobs, 

17-12 

for batch jobs, 17-11 
including command output, 17-12 
saving, 17-12 

status when batch jobs stop abnormally, 17-16 
Logging out, 2-19 

breaking dialup connection, 2-21 
deciding when it is necessary, 2-20 
from disconnected processes, 17-8 
from remote sessions, 2-20 
reasons for, 2-20 
security considerations, 2-20 
Logical device names, 12-7 
See also Device names 
Logical expressions, 14-15 

converting value data types in, 14-19 
Logical name directory tables 
See also Logical name tables 
definition, 13-11 
process, 13-12 
system, 13- 13 
Logical name tables 

See also Logical name directory tables 

access modes, 13- 11 

ACL -based protection, 13-10 

adding logical names, 13-9 

creating, 13-8, 13-9 

defining access modes, 13-7 

definition, 13-8 

deleting, 13-9, 13-16 

group, 13-8 

including user-defined tables in the search 
order, 13-9 
job, 13-8 

limiting their size, 13-10 
I i st of system-provi ded, 13- 8 
process, 13-8 
process-private, 13-8, 13-9 
quotas, 13-9 
search order, 13-6, 13-20 
shareable, 13-8, 13-9, 13-12 
system, 13-8 

U I C-based protection, 13-10 
Logical names, 1-7, 12-1 
See also Logical name tables 
access modes, 13-7 
as device names, 12-7 
attributes of, 13-7 


Logical names (cont'd) 

concealed device names, 13-4 
creating, 13-2 

creating for file specifications, 13-2 

defined as search lists, 13-5 

defining in executive mode, 13-8 

defining in user mode, 13-7 

equivalence strings, 1-7 

for mounted disks or tapes, 13-12 

for networks, 13-3 

for node specifications, 13-3, 13-4 

for work files, 11-15 

in input file lists, 13-21 

in Phone, 7-2 

placing in user-defined tables, 13-9 

preventing definition in subprocesses, 17-7 

process-permanent, 13-17, 13-18 

processing multiple tables, 13-24 

rules for creating, 13-2 

search lists, 13-5 

system-created, 13- 1 

system-permanent, 13-13 

terminal, 13-5 

to obtain output value, 15-17 

TPU$DEBUG, A- 17 

TPU$J OU RNAL, 8-31 

TPU$WORK, 8-28 

translation in file specifications, 13-3 

translations 

and wildcards, 13-6 
default search order, 13-20 
default values, 13-21 
in file specifications, 13-21 
iterative, 13-21 
preventing iterative, 13-5 
used for file input and output, 13-17 
using with directories, 13-1 
using with files, 13-1 
with print queues, 13-2 
with the OPEN command, 15-21 
Logical operators, 14-9 
table of, 14-16 
Login classes, 2-7 
See also Logins 
batch, 2-8 
dialup, 2-7 
interactive, 2-7 
local, 2-7 
network, 2-8 
non interactive, 2-8 
remote, 2-7 
restrictions on, 2-9 
Login command procedures, 15-70 
See also Command procedures 
execution of for batch jobs, 17-10 
personal, 15-70 

defining logical names in, 1-7 
definition, 1-8, 15-70 
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Login command procedures 
personal (cont'd) 

executed as batch jobs, 17-12 
location of, 15-70 
sample, 15-70 
system, 1-8 
system-defined, 15-70 
using /COM MAN D qualifier, 15-72 
Login directory files, 1-5 
Login failures 
and retries, 2-10 
causes of, 2-8 
messages, 2-7, 18-8 
Login messages, 2-6 
suppressing, 2-7 
Login programs 

authentication by secure terminal server, 2-15 
LOGIN.COM command procedures 
See Login command procedures 
Logins 

See also Proxy logins 
batch, 2-8 

changing password during, 2-12 
controlling, 2-4 
dialup, 2-7 

chances to supply password, 2-10 
disabled 

by break-in evasion, 2-10 
by shift restriction, 2-9 
for expired accounts, 2-14 
interactive, 2-7 
classes of, 2-7 
most recent, 2-6 
local, 2-7 
manual, 2-1 
monitoring last, 18-8 
network, 2-8 
non interactive, 2-7 
classes of, 2-8 
most recent, 2-7 
permitted time periods, 2-9 
remote, 2-7 

security implications, 2-3 
timeout, 2-5 

LOGOUT command, 2-19, 2-21, 17-5 
/FULL qualifier, 2-19 
/HANGUP qualifier, 2-21 
Loops 

in command procedures, 15-45 
LOWERCASE WORD command 
formatting EVE text with, 8-35 


M 

Magnetic tapes 
allocation of, 12-2 
deallocating drives, 12-3 
initializing, 12-4 
label format, 12-6 
mounting, 12-6 

See also MOUNT command 
mounting ANSI-labeled, 12-6 
volume sets 

See Volume sets 
MAIL command, 6-1 
/EDIT qualifier, 6-13 
/SUBJ ECT qualifier, 6-7 
Mail folders 
creating, 6-9 
deleting, 6-11 
displaying list of, 6-10 
MAIL, 6-3 
NEWMAIL, 6-2 
selecting, 6-10 
WASTEBASKET, 6-12 
Mail subdirectories 
creating, 6-9 
Mail utility (MAIL), 1-5 
compressi ng fi I es, 6-23 
customizing, 6-21 
deleting messages in, 6-12 
distribution lists, 6-5 
exchanging messages in, 6-18 
exiting from, 6-23 

extracting messages to files with, 6-8 
initialization files, 6-17 
invoking, 6-1 
keypad commands, 6-15 
marking messages in, 6-21 
organizing messages in, 6-20 
printing messages in, 6-19 
reading messages in, 6-2, 6-17 
removi ng messages from, 6- 19 
restrictions when sending files, 4-10 
security considerations, 6-13 
sending files, 6-6 

from DCL level, 4-10, 6-7 
sending messages over network with, 6-4 
setting default editor in, 6-14 
summary of all commands, 6-17 
system management, 6-24 
transferring control, 6-23 
using EVE in, 6-13, 6-14 
using text editors in, 6-13 
MAI L$l NIT file, 6-17 
MAIL$KEYDEF.INI file, 6-17 
sample, 6-17 


Index-17 


MAILEDIT.COM command procedure, 6-15, C-16 
Sample execution, C-17 
Margins 

setting with EVE, 8-35 
MARK command 
in EVE, 8-25 

moving the EVE cursor with, 8-8 
Marking messages 
in Mail, 6-21 
M ass storage devi ces, 1- 6 
See also Devices 
See also Disks 
See also Magnetic tapes 
Master file directories 
See MFDs 
.MEC files 

in DSR, 10-4 
Memory allocation 

in Sort/Merge utility, 11-15 
MERGE command, 1-6, 11-8 
See also Sort/Merge utility 
/FORMAT qualifier, 11-6 
/INDEXED_SEQUENTIAL qualifier, 11-6 
/KEY qualifier, 11-2, 11-9 
/NODUPLICATES qualifier, 11-5 
/OVERLAY qualifier, 11-6 
qualifiers, 11-10 
/RELATIVE qualifier, 11-6 
/SEQUENTIAL qualifier, 11-6 
/STABLE qualifier, 11-5 
Message count 

correcting in Mail with READ/NEW, 6-12 
M essage wi ndows 

displaying contents of EVE Messages buffers, 
8-40 

in EVE, 8-4 
M essages 

See System messages 
M essages buffers 

displaying contents of in EVE, 8-40 
.MEX files 

in DSR, 10-7 

MFDs (master file directories), 1-5, 5-1 
See also Directory structures 
Minikeypad, 8-5 
MODIFIABLE keyword 

to SET BUFFER command in EVE, 8-39 
MOUNT command, 12-4, 12-7 
See also DISMOUNT command 
allocating a device, 12-9 
/FOREIGN qualifier, 12-5 
specifying logical names, 12-5 
Mount requests, 12-5 
Mounting volumes 

and security audit, 18-8 


MOVE BY LINE command 

moving the EVE cursor with, 8-9 
MOVE BY PAGE command 

moving the EVE cursor with, 8-9 
MOVE BY WORD command 

moving the EVE cursor with, 8-9 
MOVE command 
in Mail, 6-9 
M ovi ng text 
in EVE, 8-16 

using the COPY command in EDT, 9-12 
using the CUT and PASTE commands in EDT, 
9-12 

Multinational collating sequence 

with sequence checking procedures, 11-7 
Multiple buffers 

editing with EVE, 8-43 
Multiple file specifications 
in a parameter list, 5-5 
Multiple input files 
in EVE, 8-30 

N 

National character set (NCS) collating sequence, 
11-7, 11-16 

Nested command procedures 
See also Command procedures 
default Ctrl/Y action, 15-61 
Network access control strings, 2-14 
Network file specifications 
See also File specifications 
See also Files 
conventional format, 4-6 
foreign file format, 4-6 
task specification strings, 4-6 
Network logins, 2-8 
Network nodes 

See also Access control strings 
See also Node names 
local, 4-5 
remote, 4-5 

remote with access control strings, 4-5 
Network security, 18-5 
Networks, 1-2, 7-2 

executi ng programs across, 1-2 
logout, 2-20 
sending mail over, 6-4 
NEW command 

for EVE buffer manipulation, 8-37 
writing EVE buffers to files, 8-41 
NEXT BUFFER command 

for EVE buffer manipulation, 8-37 
NEXT SCREEN command 

moving the EVE cursor with, 8-9 
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NEXT WINDOW command 
in EVE, 8-42 

moving the EVE cursor with, 8-9 
Node names, 1-2 

See also Access control strings 
definition, 4-1 

determining using F$SETSYI lexical function, 
16-5 

format in file specifications, 4-4 
full, 4-5 

rules for entering, 4-4 
using logical names, 13-3, 13-4 
Nokeypad editing 
in EDT, 9-1 
Nondefinable keys 
in EVE, A- 5 

Noninteractive logins, 2-7, 2-8 
classes, 2-8 
Nonprinting characters 

inserting escape characters in EVE, 8-12 
.NOT. logical operator, 14-15 
Null values, 15-9 
for file names, 4-8 
for file types, 4-8 
in command procedures, 15-10 
Numbers 

as fractions, 14-11 

as parameter values in command procedures, 
15-9 

assigning to symbols, 14-11 
converting to string values, 14-15, 14-20 
converting using lexical functions, 16-14 
evaluation of, 14-19 
in expressions, 14-12 
integer values recognized by DC L, 14-11 
internal storage of, 14-11 
Numeric expressions, 14-11 
N u meri c over I ays, 14- 14 
rules for using, 14-14 

o 

Object ownership 
changing, 18-3 
Objects 

changing security profile, 18-3 
displaying security profiles, 18-2 
security profiles, 18-2 
Octal numbers 

in a UIC directory specification, 5-8 
Offset integers 
definition, 14-10 
ON command, 15-54 

for error handling, 15-54 
keywords and actions, 15-54 
using with severity levels, 15-54 
with Ctrl/Y, 15-59 
with severity level, 15-53 


ON CONTROL_Y command, 15-57 
ONE WINDOW command 
in EVE, 8-42 
Open accounts, 2-5 
OPEN command, 15-21 to 15-32 
and logical names, 15-21 
/APPEND qualifier, 15-32 
creating a new output file using /WRITE 
qualifier, 15-30 

creating new EVE buffers with, 8-40 
for EVE buffer manipulation, 8-37 
/READ qualifier, 15-22 
reading EVE files into buffer with, 8-41 
/WRITE qualifier, 15-22 
OPEN SELECTED command 

creating new EVE buffers with, 8-40 
for EVE buffer manipulation, 8-37 
reading files into EVE buffer with, 8-41 
OpenVMS RMS 
See RMS 

Operators (mathematical) 
character strings, 14-8 
concatenating character strings with, 14-8 
definition, 14-6 
logical, 14-9, 14-15 
AND, 14-15 
NOT, 14-15 
OR, 14-16 
numeric, 14-12 
order of evaluation, 14-18 
reducing character strings, 14-8 
Optimizing sorts 

by modifying the working set extent, 11-16 
by omitting records, 11-15 
by using address sorting, 11-14 
by using index sorting, 11-14 
by using tag sorting, 11-14 
by using work files, 11-15 
.OR. logical operator, 14-16 
Organizing messages 
in Mail, 6-20 
Output 

creating a new file, 15-30 
default for interactive command procedures, 
15-2 

directing in a command procedure, 15-14 
redefining for interactive command procedures, 
15-2 

redirecting using /OUTPUT qualifier, 15-15 
suppressing by redefining SYS$OUTPUT, 
15-16 

using /OUTPUT qualifier, 15-2 
Output queues 

form options, 4-14 
Output streams, 13-12 
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Output strings 

formatting with F$FAO lexical function, 16-12 
Overlays, numeric, 14-10, 14-14 
Overstrike mode, 3-13 
in EVE, 8-11,8-27 
OVERSTRIKE MODE command 
in EVE, 8-11 
Owner (security category) 
of user access, 18-3 

P 

PI to P8 local symbols, 14-21 
Page breaks 
See Form feeds 
PAGINATE command 

formatting EVE text with, 8-35 
Paging, 11-16 
Paper shredders, 2-21 
Parameter lists 

defaults for multiple file specifications, 5-5 
multiple file specifications, 5-5 
Parameters, 3-3 

in DCL command lines, 1-4, 3-2 
passing to command procedures, 14-21, 15-9 
qualifiers, 3-8 
rules for entering, 3-6 
Parent processes, 1-8 
Password grabber programs, 2-15 
Password protection, 2-14 
avoiding detection, 2-12 
dialup retries, 2-10 
Password stealing programs, 2-15 
Passwords, 1-1 
acceptable, 2-3 
automatically generated, 2-11 
chances to supply during dialups, 2-10 
changing, 2-10 

as you log in, 2-12 
expired, 2-13 

frequency gu i del i nes, 2- 3, 2- 15 
secondary, 2-12 

using /NEW_PASSWORD qualifier, 2-12 
determining minimum length, 2-3 
dual, 2-4 

expiration, reasons for, 2-13 
failure to change, 2-13 
first, 2-3 

forced change, 2-13 
generated, 2-11 
guessing, 2-3 
guidelines, 2-2 
incorrect, 2-7 
initial, 2-3 
insecure, 2-2 
keeping former, 2-3 
length, 2-2 
lifetime of, 2-10 


Passwords (cont'd) 
locked, 2-5 
minimum length, 2-3 
new, 2-12 

omission in proxy login, 18-6 
open accounts and, 2-5 
primary, 2-4, 2-5 
reason for changing, 18-8 
restrictions, 2-3 
retries, 2-10 
reuse, 2-2 

secondary, 2-4, 2-5, 2-13 
secure choices for, 2-2 
setting a new one, 2-11 
sharing, 2-14 
system, 2-4 

entering, 2-4 
too short, 2-10 
types, 2-4 

uniqueness for each account, 2-14 
user, 2-4 

using on multiple systems, 2-14 
verifying change of, 2-11 
when account is created, 2-3 
PASTE command 

moving text in EVE with, 8-17 
Pending delete mode 
in EVE, 8-21 
Percent sign (%) 

See also Asterisk (*) 

as switchhook character in Phone, 7-2 

as wildcard character, 4-8 

with EVE file names, 8-29, 8-40 
Phone utility (PHONE), 1-6 
commands, 7-3 
conference cal Is, 7-2 
qualifiers, 7-2 

switchhook character (%) in, 7-2 
Physical device names, 12-6 
See also Device names 
Physical devices 
identifying, 12-6 
Physical security 

when logging out, 2-20 
PI D numbers, C-ll 

and process context, 17-2 
obtaining using F$PID lexical function, 16-6 
Plus sign ( +) 

as continuation character, 14-7, 15-15 
Positional qualifiers 
See also Qualifiers 
definition, 3-7 
rules for entering, 3-7 
PREVIOUS SCREEN command 
moving the EVE cursor with, 8-9 
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PREVIOUS WINDOW command 
in EVE window environment, 8-42 
moving the EVE cursor with, 8-9 
Primary passwords, 2-4 
PRI NT command, 4-13 to 4-15 
in Mail, 6-12 
/REMOTE qualifier, 4-14 
Print jobs, 4-13 
delaying, 4-15 
executing, 4-13 

list of DCL commands to use with, 4-15 
obta i n i ng mu I ti pi e copi es of, 4-15 
priorities, 4-13 
Print queues 

control I i ng, 4- 14 
defined with logical names, 13-2 
definition, 4-13 
deleting a print job from, 4-14 
Printing 

landscape, 4-15 
Printing messages 
from Mail, 6-19 
P r i vate vol u mes, 1- 7 
See also Volumes 
Privileges 
GRPNAM 

using to edit group name tables, 13-8 
GRPPRV 

using to edit group name tables, 13-8 
OPER, 16-5 
SYSNAM 

using to edit group name tables, 13-8 
using to edit logical name tables in 
executive mode, 13-7 
using to edit system directory tables, 
13-10 

SYSPRV, 13-9, 13-17, 16-5 

using to edit group name tables, 13-8 
using to edit logical name tables in 
executive mode, 13-7 
using to edit system directory tables, 
13-10 

VOLPRO, 12-4, 12-6 
Process characteristics 

lexical functions used to save and restore, 
15-69 

obtained from UAF, 1-8 
Process contexts 

list of characteristics, 17-1 
Process directory logical name tables 

list of default contents of, 13-11 to 13-13 
Process identification (PID) numbers 
See PID numbers 
Process privileges 

and process context, 17-3 


Process rights identifiers 
and process context, 17-3 
Process-permanent files, 13-12 
definition, 13-18 
Process-permanent logical names 
list of, 13-17 
P rocesses, 1- 1 

and job trees, 17-3 

changing characteristics using lexical functions, 
16-2 

checking status with Ctrl/T, 2-17 
connecting to, 2-6, 17-7 
restrictions, 2-6 
creating, 17-1 
definition, 1-8, 17-1 
disconnected, 2-6, 17-7 
displaying, 17-8 
logging out, 17-8 

displaying process rights identifiers, 18-1 
i nteracti ve mode, 2- 7 
logging out of current, 17-8 
obtaining information about 
using F$GETJ PI, 16-6 
unable to reconnect to, 2-6 
Program stubs, 15-65 

replacing with commands, 15-67 
using in command procedures, 15-68 
Programs 

as batch jobs, 1-3 
definition, 1-8 

executing across networks, 1-2 
Prompts, 3-4 

asterisk (*) line editing prompt in EDT, 9-2 
DCL, 2-2 
in Mail, 6-1 

switchhook in Phone, 7-2 
Protection 

default, 18-4 
directory, 5-6 
objects, 18-2 
of files, 4-12 
in Mail, 6-13 
Protection codes, 18-3 
access types, 18-4 
categories of, 18-3 
Proxy accounts, 1-2,18-6 
default, 18-7 
for multiple users, 18-7 
for single user, 18-7 
general access, 18-7 
maximum number allowed, 18-6 
naming, 18-7 

selecting from multiple, 18-7 
Proxy logins, 2-8, 18-6 
key characteristic, 18-7 
security benefits, 18-6 
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PURGE command, 4-12 
in Mail, 6-12 

Q 

Qualifiers 

abbreviating, 3-7 
command, 3-7 
definition, 3-3 

in DCL command lines, 1-4, 3-2 
parameter, 3-8 
positional, 3-7 
rules for entering, 3-7 
values, 3-8 

date formats, 3-8 
time formats, 3-8 
Question mark (?) 

wildcard character in Help, 2-18 
Queue options 
forms, 4-14 
Queues 

See Print queues 
batch, 17-14 

defined with logical names, 13-2 
forms, 4-14 

obtaining information about using F$GETQUI 
lexical function, 16-5 
QUIT command 
in EDT, 9-6 
in EVE, 8-7 
Quotation marks (" ") 

in nested command procedures, 15-10 
used with INQUIRE command, 15-11 
QUOTE command 
in EVE, 8-11 

R 

Radixes 

specifying in symbol assignments, 14-11 
READ command, 15-8 
See also WRITE command 
/DELETE qualifier, 15-27 
designing read loops, 15-27 
/END_OF_FILE qualifier, 15-26 
in Mail, 6-2 
/INDEX qualifier, 15-27 
/KEY qualifier, 15-27 
/NEW qualifier in Mail, 6-2, 6-12 
/PROMPT qualifier, 15-11 
reading records from indexed sequential files, 
15-27 

Reading messages 
in Mail, 6-17 
Reading records, 15-26 


Recall buffers, 18-5 
RECALL command, 3-11 
/ERASE qualifier, 18-5 
Recalling commands, 3-11,3-12 
Record file addresses 
See RFAs 

Record Management Services 
See RMS 

Record oriented devices 
definition, 1-6 

used as output to file specifications, 12-7 
Record sorting, 11-2 

See also Sort/Merge utility 
reasons for selecting, 11-14 
Records 

appending to a file, 15-32 
deleting in command procedure, 15-31 
eliminating duplicates (SORT/MERGE), 11-5 
modifying in command procedure, 15-28 
reading from a file, 15-22, 15-27 
updating, 15-28 

writing from command procedure, 15-31 
writing to a file, 15-22 
RECOVER BUFFER ALL command 
in EVE, 8-33 

RECOVER BUFFER command 
in EVE, 8-32 
Recovering files 
in EDT, 9-7 
in EVE, 8-33 
Redirecting output, 12-7 
Reinitializing volumes, 12-8 
Relative files, 11-6 

RE Ml NDER.COM command procedure, C-6 
Sample execution, C-8 
Remote logins, 2-7 
Remote nodes, 1-2 
See also Networks 
See also Node names 
obtaining information about using 
F$CONTEXT, 16-6 
printing files on, 4-14 
REMOVE command 

for EVE buffer manipulation, 8-37 
moving text in EVE with, 8-17 
Remove key 

moving text in EVE with, 8-16 
Removing messages 
in Mail, 6-19 
RENAME command, 4-10 
Repetitive substitutions, 14-27 
REPLACE command 

case sensitivity of in EVE, 8-26 
REPLY command 
in Mail, 6-8 
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RESEQUENCE command 
in EDT, 9-2 

Reserved global symbols, 14-21 
$RE START, 15-40 
RESET command 

moving text in EVE with, 8-17 
$RESTART global symbol, 14-21, 15-56 
$RESTART reserved global symbol, 15-40 
RESTORE BOX SELECTION command 
in EVE, 8-20 

RESTORE CHARACTER command 
in EVE, 8-15 
RESTORE command 
in EVE, 8-14 
RESTORE LINE command 
in EVE, 8-15 

RESTORE SELECTION command 
in EVE, 8-15 

moving text in EVE with, 8-17 
RESTORE WORD command 
in EVE, 8-15 
RETURN command, 15-41 
Return key, 3-14 

formatting EVE text with, 8-34 
REVERSE command 

moving the EVE cursor with, 8-9 
Reverse video 
in EVE, 8-16 

RFAs (record file addresses), 11-14 
Right arrow key 

moving cursor with, 3-15 
moving the cursor with in EVE, 8-8 
RMS, 2-16 

file tags in Mail, 6-6 

with READ/END_OF_FI LE command, 15-27 
.RNT files 

in DSR, 10-4 
.RNX files 

in DSR, 10-7 
RSX systems 

specifying UIC format directory names, 5-8 
RUN command 
with images, 1-9 
with processes, 17-3 
RUNOFF command, 10-1 
index qualifiers to, 10-8 
qualifiers, 10-2 

table of contents qualifiers to, 10-5 

s 

SAVE ATTRIBUTES command, A- 7, A-29 
in EVE, A-2 
with command file, A- 16 
with section file, A- 14 

SAVE EXTENDED EVE command, A- 7, A-29 
in EVE, A-2 

using to save GOLD key definitions, A-7 


SAVE FILE AS command 

for EVE buffer manipulation, 8-37 
SAVE FILE command 

for EVE buffer manipulation, 8-37 
SAVE SYSTEM ATTRIBUTES command, A- 17, 
A-28 

Saving attributes 

in a command files, A-33 
in section files, A-32 
Scoping, 15-43 
Scratchpads 
See Buffers 
Screen clearing, 2-20 
Screen layout viewports, 7-2 
Scrolling 

stopping temporarily, 4-11 
SEARCH command 
in Mail, 6-3 
Search lists, 13-1, 13-5 

and the SET DEFAULT command, 13-22 

multiple, 13-23 

nested, 13-23 

translations, 13-5 

use of, 13-22 

with file specifications, 13-5, 13-6, 13-22 
Search order 

for logical name translations, 13-20 
for multiple search lists, 13-23 
Search strings 

case sensitivity of in EVE, 8-23 
Secondary passwords, 2-4 
See also Passwords 
changing, 2-12 
disadvantages, 2-4 
entering, 2-5 
minimum length, 2-5 
running out of time to enter, 2-5 
Section files 

creating in EVE, A- 20, A-32 
definition of in EVE, A-l 
modifying in EVE, A-21 
saving EVE attributes in, A- 14, A-29, A-31 
Secure terminal servers, 2-15 
Security 

administrator, 2-4 
audit log files, 18-8 
high-level, 2-7, 18-8 
network, 18-5 
Security alarms, 18-8 
Security audit log files, 18-8 
Security auditing, 18-7 

account and file access, 18-7 
adding ACEs to files, 18-9 
deciding when to use, 18-9 
messages, 18-9 
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Security features 

account duration, 2-13,2-14 
break-in evasion, 2-10 
dialup retries, 2-10 
login class restrictions, 2-9 
password expiration, 2-13 
passwords, 2-4 to 2-15 
secure terminal servers, 2-15 
security alarms, 18-8 
shift restrictions, 2-9 
Security profiles 
objects, 18-2 

changing, 18-3 
displaying, 18-2 
processes 

displaying, 18-1, 18-2 
users 

displaying, 18-1, 18-2 
Security restrictions 
login class, 2-9 
shift, 2-9 
time-of-day, 2-9 
Security-auditing events, 18-8 
SELECT ALL command 

moving text in EVE with, 8-18 
SELECT command 

for EVE buffer manipulation, 8-37 
in Mail, 6-3,6-10 
moving text in EVE with, 8-18 
Select key 

moving text in EVE with, 8-16 
to cancel GOLD key, A-7 
Selecting a box of text 
in EVE, 8-19 

See also BOX SELECT command 
SEND command 
in Mail, 6-4, 6-6 

/EDIT qualifier, 6-14 
Sending files 
in Mail, 6-6 
restrictions, 4-10 
Sequence checking 

preventing during a Merge operation, 11-9 
Sequential files, 11-6 
Servers 

secure terminals, 2-15 
Sessions 

disconnected, 17-7 
SET BOX NOPAD command 
in EVE, 8-20 

SET BOX NOSELECT command 
in EVE, 8-20 
SET BOX PAD command 
in EVE, 8-20 

SET BOX SELECT command 
in EVE, 8-20, 8-21 


SET BUFFER command 

changing EVE editing status with, 8-39 
creating EVE scratchpads with, 8-39 
for EVE buffer manipulation, 8-38 
keywords with in EVE, 8-39 
SET CONTROLS command, 2-17 
SET CONTROL=Y command, 15-58, 15-62 
SET CURSOR BOUND command, A-34 
moving the EVE cursor with, 8-9 
SET CURSOR FREE command 
moving the EVE cursor with, 8-9 
SET DEFAULT command 

and a logical name search list, 13-22 
setting a default device with, 5-4 
setting a default directory with, 5-4 
SET DEFAULT COMMAND FILE command, 

A- 16, A-29 

SET DEFAULT SECTION FILE command, A- 14, 
A-29 

SET EDITOR command 
in Mail, 6-14 

SET ENTRY command, 17-13 

/NOCHECKPOINT qualifier, 15-40 
qualifiers to, 17-13 

SET EXIT ATTRIBUTE CHECK command, A-29 
SET FIND CASE EXACT command 
finding text in EVE with, 8-23 
SET FIND CASE NOEXACT command 
finding text in EVE with, 8-23 
SET FIND command, A-35 
SET FIND NOWHITESPACE command 
in EVE, 8-23, 8-25 
SET FIND WHITESPACE command 
in EVE, 8-23, 8-25 
SET FOLDER command, 6-10 
SET GOLD KEY command 
in EVE, A-2 
using, A-6 

SET HOST command, 2-8 
SET J OURNALING ALL command 
in EVE, 8-33 

SET J OURNALING command 
in EVE, 8-33 

SET KEYPAD EDT command, A-34 
SET LEFT MARGIN command 
formatting EVE text with, 8-35 
SET MESSAGE command, 15-18 
SET NODEFAULT COMMAND FILE command, 
A-29 

SET NODEFAULT SECTION FILE command, 

A- 15, A-29 

SET NOEXIT ATTRIBUTE CHECK command, 

A- 14, A-29 

SET NOGOLD KEY command 
in EVE, A-2 
using, A-7 
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SET NOON command, 15-56 
SET NOPENDING DELETE command 
in EVE, 8-18 

SET NOSECTION FILE PROMPTING command, 
A- 15, A-16, A-29 
SET NOSHIFT KEY command 
in EVE, A-2 
SET NOWRAP command 

formatting EVE text with, 8-36 
SET NUMBERS command 
in EDT, 9-3 

SET OUTPUT_RATE command, 17-11 
SET PARAGRAPH INDENT command 
formatting EVE text with, 8-36 
SET PASSWORD command, 2-10 
automatic password generation, 2-11 
/GENERATE qualifier, 2-11 
/SECONDARY qualifier, 2-12 
SET PENDING DELETE command 
in EVE, 8-18 

SET PREFIX command, 15-20,17-12 
SET PROCESS command 
/NAME qualifier, 17-2 
SET PROTECTION command 
/DEFAULT qualifier, 18-4 
SET QUEUE command 
/ENTRY qualifier, 17-13 
in Mail, 6-12 
qualifiers to, 17-13 

SET RESTART_VALUE command, 15-40, 15-56 
SET RIGHT MARGIN command, A-35 
formatting EVE text with, 8-35 
SET SCROLL MARGINS command, A-35 
moving the EVE cursor with, 8-10 
SET SECTION FILE PROMPTING command, 

A- 14, A-29 

SET SECURITY command 
/ACL qualifier, 13-10 
changing object security profile, 18-3 
/OWNER qualifier, 18-3 
/PROTECTION qualifier, 18-3, 18-4, 18-5 
SET SHIFT KEY command 
in EVE, A-2 

SET SYMBOL command, 14-22 
/SCOPE qualifier, 14-22 
SET TABS AT command 

formatting EVE text with, 8-36 
SET TABS EVERY command 
formatting EVE text with, 8-36 
SET TABS INSERT command 
formatting EVE text with, 8-36 
SET TABS INVISIBLE command 
formatting EVE text with, 8-36 
SET TABS MOVEMENT command 
formatting EVE text with, 8-36 
SET TABS SPACES command 
formatting EVE text with, 8-36 


SET TABS VISIBLE command 
formatting EVE text with, 8-36 
SET TERMINAL command, 3-13, 17-5 
/APPLICATIONJCEYPAD qualifier, 3-14 
/BROADCAST qualifier, 2-17 
/HANGUP qualifier, 2-21 
/INSERT qualifier, 3-13 
/LINE_EDIT qualifier, 3-13 
/NONUMERIC qualifier, 3-14 
/OVERSTRIKE qualifier, 3-13 
/WRAP qualifier, 3-13 
SET VERIFY command, 15-19 

debugging command procedures with, 15-19, 
15-66 

SET Wl DTH command 

in EVE window environment, 8-42 
SET Wl LDCARD VMS command 
in EVE, 8-23 
SET WRAP command 

formatting EVE text with, 8-36 
Set-Up key, 2-20 
$SEVERITY global symbol, 14-21 
commands that do not set, 15-53 
definition, 15-52 

testing for successful (odd) value, 15-53 
value with SET NOON, 15-56 
Shareable files 

using /SHARE qualifier to open, 15-23 
Shareable logical name tables, 13-8 
See also Logical name tables 
creating, 13-9 

group logical name tables, 13-13 
privilege and access requirements, 13-9 
system logical name tables, 13-13 
user-defined, 13-9 
SHIFT LEFT command 

in EVE window environment, 8-42 
moving the EVE cursor with, 8-10 
Shift restrictions, 2-9 
SHIFT RIGHT command 

in EVE window environment, 8-42 
moving the EVE cursor with, 8-10 
SHOW BUFFERS command 

for EVE buffer manipulation, 8-38 
SHOW command 

for EVE buffer manipulation, 8-38 
in EVE, 8-38 

SHOW DEFAULT command, 5-4, 16-1 
SHOW DEFAULTS BUFFER command 
for EVE buffer manipulation, 8-38 
SHOW DEVICES command, 12-2 
SHOW ENTRY command, 4-13, 17-9, 17-14 
/FULL qualifier, 17-15 
SHOW LOGICAL command 

displaying logical name tables, 13-15 
including wildcards, 13-15 
/TABLE qualifier, 13-16 
with logical name access modes, 13-15 
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SHOW LOGICAL command (cont'd) 

with logical name table structures, 13-16 
SHOW PROCESS command, 17-3, 18-1 
/ALL qualifier, 17-1 
/MEMORY qualifier, 17-3 
/PRIVILEGES qualifier, 17-3 
/SUBPROCESSES qualifier, 17-3 
SHOW QUEUE command, 4-13, 17-14 
/FULL qualifier, 17-11,17-15 
SHOW SECURITY command 

displaying security profiles of objects, 18-2 
SHOW SUMMARY command, A-21 
SHOW SYMBOL command, 15-20 
/ALL qualifier, 14-4 

debugging command procedures with, 15-66 
with lexical functions, 14-16 
SHOW SYSTEM BUFFERS command 
for EVE buffer manipulation, 8-38 
SHOW TERMINAL command, 3-13 
SHOW USERS command 
and disconnected jobs, 17-8 
SHOW WILDCARDS command 
in EVE, 8-23 

SHRINK WINDOW command 

in EVE window environment, 8-42 
SORT command, 1-6, 11-2 
See also Sort/Merge utility 
/FORMAT qualifier, 11-6 
/INDEXED_SEQUENTIAL qualifier, 11-6 
/KEY qualifier, 11-2 
/NODUPLICATES qualifier, 11-5 
/OVERLAY qualifier, 11-6 
/RELATIVE qualifier, 11-6 
/SEQUENTIAL qualifier, 11-6 
/STABLE qualifier, 11-5 
Sorti ng 

batch jobs, 11-7 
character data, 11-6 
collating sequences, 11-6 
keys, 11-4 
output files, 11-6 
terminal input, 11-10 
types of, 11-14 

Sort/Merge utility (SORT/MERGE) 

See also Sorting 
collating sequences 
ASCII, 11-6 
EBCDIC, 11-6 
command qualifiers, 11-16 
creating sequential files, 11-6 
entering records from terminal with, 11-10 
invoking, 1-6 

memory allocation in, 11-15 
mergi ng fi I es wi th , 11-8 
optimizing, 11-13 
output file, 11-6 

sorting noncharacter data files with, 11-7 
sorting records with, 11-2 


Sort/M erge ut i I i ty (SO RT/M E RG E ) 
sorting records with (cont'd) 
by key field, 11-3 
in ascending order, 11-3 
using identical key fields, 11-5 
using multiple key fields, 11-4 
specification files, 11-11 
SPAWN command, 17-3 
/INPUT qualifier, 17-4 
list of qualifiers, 17-6 
/NOWAIT qualifier, 17-4 
/OUTPUT qualifier, 17-4 
restriction on using in EVE, 8-43 
Specification files, 11-11 to 11-12 
SPLIT WINDOW command 
in EVE, 8-42 
START OF LINE command 

moving the EVE cursor with, 8-10 
Start position 
in EVE, 8-28 
Startup files 

in EVE, A-l, A-28, A-30 
$STATU S global symbol, 14-21, 15-42 
commands that do not set, 15-53 
definition, 15-51 
format of, 15-51 
in error handling, 15-53 
severity of error condition, 15-52 
testing for successful (odd) value, 15-53 
value with SET NOON, 15-56 
Status lines 
in EVE, 8-4 

STOP command, 15-6, 15-7, 15-50, 15-58 
STORE TEXT command 

moving text in EVE with, 8-18 
String comparisons, 14-9 
String variables 

in DECTPU procedures, A- 19 
Strings 

comparing, using operators, 15-37 
concatenating, 14-5 
continuation over multiple lines, 14-7 
converting to integer values, 14-20 
Stubs 

See Program stubs 
Subdirectories, 1-5 
See also Directories 
creating, 5-3 
listing, 5-3 

setting default to another, 5-4 
syntax, 5-2 

SUBMIT command, 17-9 
/AFTER qualifier, 17-9 
/KEEP qualifier, 17-12 
/LOG qualifier, 17-12 
/NOPRINT qualifier, 17-12 
/PARAMETERS qualifier, 15-10 
qualifiers for controlling batch jobs, 17-14 
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SUBMIT command (cont'd) 

/RESTART qualifier, 15-2, 15-41, 17-16 
specifying multiple command procedures with, 
17-10 

Subprocesses, 1-8 
See also Processes 
and job trees, 17-3 

and process identification number, 17-6 
context, 17-6 
creating, 17-4 
creating from EVE, 8-43 
definition, 17-3 
deleting, 17-5 
exiting from, 17-5 
leaving from EVE, 8-43 
SUBROUTINE command, 15-43 
Subroutines 

defi n i ng scope of, 15- 43 
entry points in DCL, 15-43 
nesting, 15-43 

optional parameter restrictions, 15-42 
transferring control to with CALL command, 
15-42 

transferring control to with GOSUB command, 
15-41 

Substitution operators 
ampersand (& ), 14-25 
apostrophe ('), 14-25 
definition, 14-24 
order of evaluation, 14-25,14-26 
Substrings 

rules for replacing, 14-10 
Switchhook character (%) 
in Phone, 7-2 

SYLOGI N. COM command procedure, 17-8 
Symbol substitutions 

See also Iterative substitutions 
See also Substitution operators 
in command procedures, 14-27 
operators, 14-24 

performed by command interpreter, 14-26 
rules for using ampersands (& ), 14-26 
using an ampersand (& ), 14-25 
using an apostrophe ( '), 14-25 
within quoted character strings, 14-25 to 
14-28 

Symbol tables, 14-20 

See also Global symbol tables 
See also Local symbol tables 
search order, 14-21 
Symbols, 14-1 

See also Global symbols 

See also Local symbols 

and F$TYPE lexical function, 16-15 

as foreign commands, 1-4 

as parameter values, 15-9 

as variables, 14-1 


Symbols (cont'd) 
assignment, 14-2 
concatenation, 14-5 
creating, 14-2 

defined as lexical functions, 14-16 
deleting, 14-5 
displaying, 14-4 

in command procedures, 15-15 
evaluating, 14-19 

evaluating using I F command, 15-37 

global, 14-2 

in expressions, 14-7 

indicating numeric values, 14-11, 14-19 

iterative substitutions, 14-27 

local, 14-2 

logical data, 14-14 

masking values of, 14-22 

numeric overlays with, 14-14 

passing to a command procedure, 15-9 

performing arithmetic operations, 14-12 

precedence, 14-21 

preventing assignments in subprocesses, 17-7 
repetitive substitutions, 14-27 
rules for abbreviating, 14-3 
search order, 14-21 
substitution, 14-23 
automatic, 14-23 
forced, 14-23 
order of, 14-24 

substring replacement with, 14-10 
table of numeric comparisons, 14-13 
undefined, 14-29 
used as variables, 14-6 
used in expressions, 14-6, 14-7 
using equal sign ( =) to define, 14-4 
using to define other symbols, 14-5 
with the WRITE command, 15-25 
SYMBOL_SCOPE argument 

to F$ENVIRONMENT lexical function, 14-22 
SYNCHRONIZE command, 17-16 
Syntax 

diagram for DCL commands, 3-4 
file specifications on tape volumes, 4-8 
for DCL commands, 1-4, 3-4 
foreign commands, 14-4 
node specifications, 4-4 to 4-7 
VMScluster device specifications, 12-8 
SYS$BATCH logical name, 17-9 
SYS$COMMAND logical name 
process-permanent files, 13-17 

using to define SYS$I NPUT as your 
terminal, 15-12 
redefining, 13-20 
SYS$ERROR logical name 
in log files, 17-12 

process-permanent files, 13-17,17-11 
redefining, 13-19 
redirecting, 15-18 
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SYS$INPUT logical name 
defined as a datafile, 15-13 
defined as an input file, 15-13 
process-permanent files, 13-17,17-10 
redefining, 13-18 

in command procedure, 15-12 
SYS$LOGIN logical name, 13-1, 15-70 
SYS$OUTPUT logical name 
in log files, 17-12 

process-permanent files, 13-17,17-11 
redefining, 15-16 
redefining, 13-18 

in supervisor mode, 13-19 
SYS$PRINT logical name, 4-13 
and batch job log files, 17-12 
SYS$SCRATCH logical name 
in Sort/Merge utility, 11-15 
SYS$SYSTEM logical name, 13-1, 14-4 
SYS.COM command procedure, C-ll 
Sample execution, C-12 
SYSGEN (System Generation utility) 

See System Generation utility 
SYSNAM privilege 

using to edit logical name tables in executive 
mode, 13-7 

using to edit system directory tables, 13-10 
using to edit system name tables, 13-8 
SYSPRV privilege 

using to delete sharable logical name tables, 
13-17 

using to edit group name tables, 13-8 
using to edit logical name tables in executive 
mode, 13-7 

using to edit shareable logical name tables, 
13-9 

using to edit system directory tables, 13-10 
System directory logical name tables 
list of default contents, 13-13 
System error messages 
redirecting, 15-18 
System failures 

disposing of hardcopy output, 2-21 
security implications, 2-15 
System Generation utility (SYSGEN), 13-11 
System logical name tables 
definition, 13-13 
list of default contents, 13-13 
logical names for, 13-13 
System management commands 
in Mail, 6-24 
System messages 
announcement, 2-6 
auditing, 18-9 
deciphering, 2-16 
disconnected job, 2-6 
error 

command procedure to suppress, 15-18 


System messages 
error (cont'd) 

description of, 2-16 
in read loops, 15-27 
suppressing using /ERROR qualifier, 
15-32 

with COPY command, 4-10 
informational, 2-16 
last successful interactive login, 2-6 
last successful noninteractive login, 2-7 
login, 2-6 
login failure, 18-8 
new mail, 2-7 
number of login failures, 2-7 
responses to commands, 2-15 
suppressing, 2-7 
welcome, 2-6 
System objects 

using logical names with, 13-1 
System passwords, 2-4 
causing login failures, 2-9 
entering, 2-4 
System privileges 

protecti ng fi I es, 4-12 
SYSNAM 

editing system name tables, 13-8 
using to edit logical name tables in 
executive mode, 13-7 
using to edit system directory tables, 
13-10 

SYSPRV 

editing system name tables, 13-8 
using to edit logical name tables in 
executive mode, 13-7 
using to edit system directory tables, 
13-10 

System security 
audit log file, 18-8 

System-permanent logical names, 13-13 
Systems 

control ling access to, 2- 7 
control I ing use of, 2-4 

T 

Tab key, 3-15 

formatting EVE text with, 8-34 
Tab stop 

advancing to using Ctrl/K, 3-16 
Table of contents 

creating in DSR, 10-4 
Tag sorting, 11-14 

reasons for selecting, 11-14 
Tape volumes 
See also Volumes 
command procedures with, 15-3 
file specifications, 4-8 
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Tapes 

ANSI volume file specification format, 4-8 
Task specification strings 
on networks, 4-6 
Task-to-task communications, 1-2 
Temporary defaults in input file lists, 5-5 
Terminals 

breaking dialup connection, 2-21 
clearing the screen, 2-20,18-5 
control characters, D-2 
control keys, D- 1 
control I i ng access to, 2-4 
dialup login, 2-7 
failing to respond, 2-4 
hard copy 

disposing of output, 2-21 
HOLD SCREEN function key, 4-11 
I/O in command procedure, 15-12 to 15-14 
logout considerations, 2-20 
reconnecting to, 17-7 
requiring a system password, 2-9 
special keys, D-l, D-2 
stopping and starting displays, 3-16 
system password, requirement for, 2-4 
virtual, 2-6, 17-8 
VT200 series function keys, D-l 
VT300 series function keys, D-l 
Text editors 

See also EDT editor 
See also EVE 
definition, 1-6 
THEN command, 15-34 
Time 

See also Absolute time 
See also Combination time 
See also Delta time 

specifying absolute and delta date and time 
combinations, 3-10 
specifying absolute date and time, 3-9 
specifying delta date and time, 3-10 
Time-of-day login restrictions, 2-9 
Time-stamping, 16-4 

using SET PREFIX command, 15-20, 17-12 
Timeout periods, 2-1 

on virtual terminals, 17-7 
TOP command 

moving the EVE cursor with, 8-10 
Top-level directories, 5-1 
TPU command, A- 18 
TPU$DE BUG logical name, A- 17 
TPU $J OURNAL logical name, 8-31 
TPU$WORK logical name, 8-28 
Transferring control 
in Mail, 6-23 
TWO Wl NDOWS command 
in EVE, 8-42 


TYPE command, 15-5, 15-15 
and wildcard characters, 4-11 
displaying files on remote nodes with, 4-11 
displaying files with, 4-11 
displaying files with in EDT, 9-2 
executing command procedure on remote node 
with, 15-2 
/PAGE qualifier, 4-11 
TYPE WHOLE command 
in EDT, 9-2 

u 

UAFs (user authorization files), 2-3 
account expiration, 2-14 
LOCKPWD flag, 2-5 
login class restrictions, 2-9 
modifications and security audit, 18-8 
process characteristics, 1-8 
record of last login, 18-8 
UFDs (user file directories) 

See also Directory structures 
contents of, 1-5 
location of, 1-6 

UIC directory specifications, 5-8 
translating to named format, 5-8 
UIC identifiers 
example, 18-2 

UlCs (user identification codes) 
and process context, 17-2 
default protection, 18-4 
UNDEFINE KEY command 
in EVE, A-3 

Undefined symbols, 14-29 
Unit number field, 12-8 
default value, 12-7 
Unit record devices, 1-6 
UN MODI FI ABLE keyword 

to SET BUFFER command in EVE, 8-39 
Up arrow key 

moving the cursor with in EVE, 8-8 
recalling commands with, 3-11,3-15 
UPPERCASE WORD command 
formatting EVE text with, 8-36 
User authorization files 
See UAFs 
User file directories 
See UFDs 

User identification codes 
See UlCs 
User names, 1-1 
User passwords 
See Passwords 
Users 

displaying process rights identifiers, 18-1 
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V 

Values, 3-3 

in DCL command lines, 1-4, 3-2 
Variables, 14-6 
VE RB_SCOPE argument 

to F$ENVIRONMENT lexical function, 14-22 
Video terminals 
SeeTerminals 
Viewports 

in Phone, 7-2 
Virtual terminals 
See also Terminals 
disabling, 2-6 

disconnected processes and, 17-8 
displaying disconnected processes, 17-8 
logging out of, 17-8 
managing disconnected processes, 17-8 
reconnecting to disconnected processes, 17-7 
restrictions, 17-8 
VMSduster device names 
See also Devices 
allocation class fields, 12-8 
format 

for dual-pathed devices, 12-8 
in file specifications, 12-8 
node field, 12-8 

VOLPRO (Volume Protection Override), 12-4, 
12-6 

Volume Protection Override 
See VOLPRO 
Volume sets, 12-6 
disk, 12-7 
mounting, 12-4 
tape, 12-7 
Volumes, 1-7, 12-1 
creating, 12-1 
foreign, 12-5 
initializing, 12-3, 12-4 
label format, 12-6 
magnetic tape 

mounting, 12-6 
mounting, 12-4 to 12-6 
operator assistance, 12-5 
private, 12-1 
VTlOO-series terminals 
clearing screen, 2-20 
VT200-series terminals 
clearing screen, 2-20 


Welcome messages 

See System messages, welcome 
Wildcard characters, 3-4 
asterisk (*), 4-7 
in Help, 2-18 

default patterns in EVE, 8-25 
displaying logical names with, 13-15 
ellipsis (... ), 5-7 
hyphen (-), 5-8 
in file names in EVE, 8-29 
in file specifications containing logical names, 
13-6 

in search strings in EVE, 8-25 
percent si gn ( % ), 4-8 
question mark (?) in Help, 2-18 
with EVE file specifications, 8-12 
WILDCARD FIND command 
finding text in EVE with, 8-23 
in EVE, 8-25 
Wi ndows 

in EVE, 8-4 

using multiple in EVE, 8-41 
Work files 

assigning using /WORK_FI LES clause, 11-15 
in EVE, 8-28 
logical names for, 11-15 
Sort/M erge uti I ity, 11- 15 
Working set extent, 11-16 
WPS keypad option 
in EVE, 8-6 
WPS Ruler key 

for tab stops, A- 37 

WRITE command, 14-27, 15-14, 15-23 
See also READ command 
/SYMBOL qualifier, 15-26 
/UPDATE qualifier, 15-26 
updating records using /UPDATE qualifier, 
15-28 

used with F$FAO lexical function, 16-12 
with different data types, 15-14 
with symbols, 15-25 
writing strings to records, 16-12 
WRITE FILE command 

for EVE buffer manipulation, 8-38 
writing EVE buffers to files, 8-41 
WRITE keyword 

to SET BUFFER command in EVE, 8-39 


w 

WAIT command 

synchronizing command procedures, 17-16 
WASTEBASKET folder 
emptying in Mail, 6-12 
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